Poster | Thread |
Trixie
| |
Re: Autodoc replacement Posted on 6-Jan-2020 7:11:32
| | [ #21 ] |
|
|
|
Amiga Developer Team |
Joined: 1-Sep-2003 Posts: 2090
From: Czech Republic | | |
|
| @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 |
|
Status: Offline |
|
|
CygnusEd
| |
Re: Autodoc replacement Posted on 6-Jan-2020 11:42:18
| | [ #22 ] |
|
|
|
Regular Member |
Joined: 7-Feb-2004 Posts: 393
From: germany | | |
|
| @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 |
|
Status: Offline |
|
|
olsen
| |
Re: Autodoc replacement Posted on 6-Jan-2020 13:50:09
| | [ #23 ] |
|
|
|
Cult Member |
Joined: 15-Aug-2004 Posts: 774
From: Germany | | |
|
| @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.
|
|
Status: Offline |
|
|
Chris_Y
| |
Re: Autodoc replacement Posted on 6-Jan-2020 21:04:29
| | [ #24 ] |
|
|
|
Elite Member |
Joined: 21-Jun-2003 Posts: 3204
From: Beds, UK | | |
|
| @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 |
|
Status: Offline |
|
|
asymetrix
| |
Re: Autodoc replacement Posted on 6-Jan-2020 22:00:34
| | [ #25 ] |
|
|
|
Cult Member |
Joined: 9-Mar-2003 Posts: 868
From: United Kingdom | | |
|
| |
Status: Offline |
|
|
ssolie
| |
Re: Autodoc replacement Posted on 6-Jan-2020 22:28:12
| | [ #26 ] |
|
|
|
Elite Member |
Joined: 10-Mar-2003 Posts: 2755
From: Alberta, Canada | | |
|
| @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 |
|
Status: Offline |
|
|
ssolie
| |
Re: Autodoc replacement Posted on 6-Jan-2020 22:30:03
| | [ #27 ] |
|
|
|
Elite Member |
Joined: 10-Mar-2003 Posts: 2755
From: Alberta, Canada | | |
|
| @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 |
|
Status: Offline |
|
|
ssolie
| |
Re: Autodoc replacement Posted on 6-Jan-2020 22:33:36
| | [ #28 ] |
|
|
|
Elite Member |
Joined: 10-Mar-2003 Posts: 2755
From: Alberta, Canada | | |
|
| @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 |
|
Status: Offline |
|
|
ssolie
| |
Re: Autodoc replacement Posted on 6-Jan-2020 22:36:37
| | [ #29 ] |
|
|
|
Elite Member |
Joined: 10-Mar-2003 Posts: 2755
From: Alberta, Canada | | |
|
| @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 |
|
Status: Offline |
|
|
Trixie
| |
Re: Autodoc replacement Posted on 7-Jan-2020 7:13:54
| | [ #30 ] |
|
|
|
Amiga Developer Team |
Joined: 1-Sep-2003 Posts: 2090
From: Czech Republic | | |
|
| @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 |
|
Status: Offline |
|
|
kolla
| |
Re: Autodoc replacement Posted on 7-Jan-2020 7:46:17
| | [ #31 ] |
|
|
|
Elite Member |
Joined: 21-Aug-2003 Posts: 2917
From: Trondheim, Norway | | |
|
| 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 |
|
Status: Offline |
|
|
CygnusEd
| |
Re: Autodoc replacement Posted on 7-Jan-2020 14:21:26
| | [ #32 ] |
|
|
|
Regular Member |
Joined: 7-Feb-2004 Posts: 393
From: germany | | |
|
| @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 |
|
Status: Offline |
|
|
CygnusEd
| |
Re: Autodoc replacement Posted on 7-Jan-2020 14:24:45
| | [ #33 ] |
|
|
|
Regular Member |
Joined: 7-Feb-2004 Posts: 393
From: germany | | |
|
| @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 |
|
Status: Offline |
|
|
NutsAboutAmiga
| |
Re: Autodoc replacement Posted on 7-Jan-2020 17:59:39
| | [ #34 ] |
|
|
|
Elite Member |
Joined: 9-Jun-2004 Posts: 12825
From: Norway | | |
|
| 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 |
|
Status: Offline |
|
|
asymetrix
| |
Re: Autodoc replacement Posted on 7-Jan-2020 21:11:01
| | [ #35 ] |
|
|
|
Cult Member |
Joined: 9-Mar-2003 Posts: 868
From: United Kingdom | | |
|
| @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 :) |
|
Status: Offline |
|
|