@CygnusEd

Quote:

So why not enhance "AD2AG"

Even better - enhance the AutoDoc tool so that it extracts documentation from source files and supports multiple output formats: plain text, AmigaGuide, HTML, PDF...

_________________
The Rear Window blog

AmigaOne X5000/020 @ 2GHz / 4GB RAM / Radeon RX 560 / ESI Juli@ / AmigaOS 4.1 Final Edition
SAM440ep-flex @ 667MHz / 1GB RAM / Radeon 9250 / AmigaOS 4.1 Final Edition

@Trixie

Not bad, but this tool could only be used by OS developers because the sources are not public - the autodocs and includes are. So also other developer could use it (with xrefs to the OS content).

Maybe it would be a good idea to create such a tool with Hollywood. It has Polybios for PDF and HTML should also be possible. And you would have a GUI, which could be compiled on every platform.

_________________
X-5000 PPC 5020/2 GHZ, Fractal Define XL R2-Tower, OS 4.1 final update 2, 4 GB, Radeon HD 7770, ESI Juli@ XTe
SAM 460ex/1,15 GHZ, OS 4.1 final, 2 GB, Radeon HD 6450
Amiga 4000D/040 25 Mhz, OS 3.9 BB2, 272 MB, X-Surf, 250 MB ZIP

@ssolie

Quote:

ssolie wrote: What do you think would be the best replacement for good old Autodoc? Here is the spec we have been following: https://wiki.amigaos.net/wiki/Autodoc_Style_Guide What we need today is a cross-platform tool (AmigaOS, Linux, Windows) which will be able to handle the usual library/function/method stuff but with a couple of unique twists: 1. Capability to properly document tags. Tags have an ID, default value and type. 2. Capability to handle our library/interface feature. Libraries are split into one or more interfaces which have one or more methods. I've seen all sorts of suggestions but nothing seems to fit just right. ... Maybe the answer is to just add markup to Autodoc and extend it a bit.

I've just had the questionable pleasure of spelunking in the very old operating system corners during the Christmas holidays.

For the very first time I may have actually come to understand what the AutoDocs are and what makes them "work".

The name "AutoDoc" provides one of the clues: Auto = self, Doc = Documentation. Another clue is in who isn't creating this documentation. Commodore/Amiga's in-house documentation intended for 3rd party developers (the ROM Kernel Reference Manuals) was written by dedicated personnel whose primary job was to edit and shape it, and it drew upon the AutoDocs to accomplish this.

Hence, the "AutoDocs" are the documentation which the operating system developers wrote by themselves. As such it has to follow a certain structure and form (which is why the style guide exists) and it is geared towards making it easy for the respective developers to create it. This structural framework and the ease of production are what made the AutoDocs "work".

This is what one could build upon, keeping an eye on how easy it is to author and maintain the documentation.

The editors/authors of the ROM Kernel Reference Manuals provided feedback on the structure and quality of the AutoDocs, and much of that was done by individually reviewing the AutoDoc text. It would be helpful if this kind of work could be automated to some degree, catching structural errors in the text.

The AutoDoc structure itself is rather weak and requires that the author observes line lengths and formatting. This should not be generally necessary since you're at some point going to spend a lot of time in getting the line lengths right, the line breaks, etc. Having a template to fill in is helpful, but in the end this is all plain text which does not lend itself to automated processing.

I think it would be helpful if the template would not require you to observe the line lengths, the line breaks, etc. An automated process should be able to extract the AutoDocs, format them to match the specs and put them back into the code. This does not need to be done through adding markup (easy of production?). The respective section headings in the AutoDoc template could indicate which kind of format to expect. If the AutoDoc processing tool detected mismatches in the expected contents (which doesn't follow the expected form) it could flag these and suggest edits.

Last edited by olsen on 06-Jan-2020 at 01:52 PM.

@CygnusEd

Quote:

CygnusEd wrote: @ssolie My suggestion: Keep the autodoc format as it is and use a tool to create the desired documentation out of the autodoc and the include files. Personally I use the old Commodore tool "AD2AG" to convert the autodocs provided with the SDK into more comfortable amigaguide files. "AD2AG" adds cross references to functions, structures, include files etc.. Every function has it's own page that contains links built using the mentioned cross references. See snapshots: Snap1 , Snap2 So why not enhance "AD2AG" or create a new tool, that can output PDF or HTML (...) files with the content and layout you need? This tool could read all informations out of the autodoc and the include files, create a files format, which could be read on all platforms and the autodoc format is untouched.

I use the old xref tool (xref.library?) on Aminet which does the same thing but is more broken. Don't know why I didn't know about AD2AG!

The AmigaGuide can be run through GuideML afterwards to get HTML files, although personally I find AmigaGuide much quicker and easier to read on an Amiga.

_________________
"Miracles we do at once, the impossible takes a little longer" - AJS on Hyperion
Avatar is Tabitha by Eric W Schwartz

@thread

You could go further and use software that generates class diagrams from UML or source code.

XML for structure maybe a definition file.

Asciidoc is nice, can be used with source code documentation and output many formats.

asciidoc vs markdown

_________________
Download 499.26 Mbps, 659.94 Mbps Upload :)

@khayoz
Quote:

Otherwise Robodoc, Headerdoc when looking at language support.

Those two were certainly on my initial short list.

However, the question on how to properly markup the tags is still an issue.

_________________
ExecSG Team Lead

@sTix
Quote:

If nothing out there seems to fit just right then I'd go for extending autodocs. If that fails / becomes messy for some reason, then atleast you know exactly what your needs are.

Yeah, that is probably what we'll end up doing. If we extend Autodoc to do markup it might be good enough.

_________________
ExecSG Team Lead

@CygnusEd
Quote:

My suggestion: Keep the autodoc format as it is and use a tool to create the desired documentation out of the autodoc and the include files.

The problem with Autodocs is that they are completely free form which makes them impossible to parse. At a minimum we need to add some kind of markup.

_________________
ExecSG Team Lead

@asymetrix
Quote:

Asciidoc is nice, can be used with source code documentation and output many formats.

Interesting. I didn't know about that one.

_________________
ExecSG Team Lead

@ssolie, asymetrix

The problem with asciidoc is that it doesn't have a C/C++ implementation AFAIK.

_________________
The Rear Window blog

AmigaOne X5000/020 @ 2GHz / 4GB RAM / Radeon RX 560 / ESI Juli@ / AmigaOS 4.1 Final Edition
SAM440ep-flex @ 667MHz / 1GB RAM / Radeon 9250 / AmigaOS 4.1 Final Edition

Searchable free text always wins, simple markdown is a plus. The problem with amigaguide is that Multiview has no functional “search” implemented for this datatype. (Hm, didn’t the old AmigaGuide program have that?)

_________________
B5D6A1D019D5D45BCC56F4782AC220D8B3E2A6CC

@Chris_Y

You can find AD2AG on the Amiga-Developer CD V2.1. Using this tool is a bit tricky, so if you need help, send me a PM
Little disadvantage: With a few autodocs AD2AG crashes, so I had to sort them out. But most autodocs work.

Didn't know about GuideML. Sounds interesting, but I also prefer AmigaGuide.

_________________
X-5000 PPC 5020/2 GHZ, Fractal Define XL R2-Tower, OS 4.1 final update 2, 4 GB, Radeon HD 7770, ESI Juli@ XTe
SAM 460ex/1,15 GHZ, OS 4.1 final, 2 GB, Radeon HD 6450
Amiga 4000D/040 25 Mhz, OS 3.9 BB2, 272 MB, X-Surf, 250 MB ZIP

@ssolie

Quote:

ssolie wrote: @CygnusEd The problem with Autodocs is that they are completely free form which makes them impossible to parse. At a minimum we need to add some kind of markup.

Hmm - but AD2AG can handle most of them (O.K. - tested it only with the autodocs included in the SDK). So it seems to be possible to parse them in some way.

_________________
X-5000 PPC 5020/2 GHZ, Fractal Define XL R2-Tower, OS 4.1 final update 2, 4 GB, Radeon HD 7770, ESI Juli@ XTe
SAM 460ex/1,15 GHZ, OS 4.1 final, 2 GB, Radeon HD 6450
Amiga 4000D/040 25 Mhz, OS 3.9 BB2, 272 MB, X-Surf, 250 MB ZIP

Mark down is what GIT use, so it make sense to have a simple mark down viewer, for .md files.

Should it be a autodoc replacement I don't think so, its nice for small docs, but its a data base or wiki system.

It was not created to enforce versioning or anything like that, but then again versioning you get for free on GIT.

Last edited by NutsAboutAmiga on 07-Jan-2020 at 07:41 PM.

_________________
http://lifeofliveforit.blogspot.no/
Facebook::LiveForIt Software for AmigaOS

@Trixie

One could use multiple parsers for different areas at different stages using specific tools.

I was thinking yesterday that linux have the automated man tools and use cross reference for the API thats displayed online.

I think an IDE that parses C code use a database for autocomplete.

It takes careful planning, in stages of growth and perfection.

An expert devop and data scientist is a must.

_________________
Download 499.26 Mbps, 659.94 Mbps Upload :)