Click Here
home features news forums classifieds faqs links search
5752 members 
Amiga Q&A /  Free for All /  Emulation /  Gaming / (Latest Posts)
Login

Nickname

Password

Lost Password?

Don't have an account yet?
Register now!

Support Amigaworld.net
Your support is needed and is appreciated as Amigaworld.net is primarily dependent upon the support of its users.
Donate

Menu
Main sections
» Home
» Features
» News
» Forums
» Classifieds
» Links
» Downloads
Extras
» OS4 Zone
» IRC Network
» AmigaWorld Radio
» Newsfeed
» Top Members
» Amiga Dealers
Information
» About Us
» FAQs
» Advertise
» Polls
» Terms of Service
» Search

IRC Channel
Server: irc.amigaworld.net
Ports: 1024,5555, 6665-6669
SSL port: 6697
Channel: #Amigaworld
Channel Policy and Guidelines

Who's Online
12 crawler(s) on-line.
 16 guest(s) on-line.
 2 member(s) on-line.


 megol,  klapdeur

You are an anonymous user.
Register Now!
 megol:  28 secs ago
 klapdeur:  2 mins ago
 emeck:  6 mins ago
 gryfon:  11 mins ago
 BigD:  20 mins ago
 terminills:  20 mins ago
 Hypex:  26 mins ago
 pixie:  28 mins ago
 towo2099:  35 mins ago
 OneTimer1:  39 mins ago

/  Forum Index
   /  Amiga OS4.x \ Workbench 4.x
      /  Autodoc replacement
Register To Post

Goto page ( Previous Page 1 | 2 )
PosterThread
Trixie 
Re: Autodoc replacement
Posted on 6-Jan-2020 7:11:32
#21 ]
Amiga Developer Team
Joined: 1-Sep-2003
Posts: 1939
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...

_________________
Smoke me a kipper, I'll be back for breakfast!

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
Profile     Report this post  
CygnusEd 
Re: Autodoc replacement
Posted on 6-Jan-2020 11:42:18
#22 ]
Regular Member
Joined: 7-Feb-2004
Posts: 384
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 pre, 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
Profile     Report this post  
olsen 
Re: Autodoc replacement
Posted on 6-Jan-2020 13:50:09
#23 ]
Cult Member
Joined: 15-Aug-2004
Posts: 725
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
Profile     Report this post  
Chris_Y 
Re: Autodoc replacement
Posted on 6-Jan-2020 21:04:29
#24 ]
Elite Member
Joined: 21-Jun-2003
Posts: 3139
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
Profile     Report this post  
asymetrix 
Re: Autodoc replacement
Posted on 6-Jan-2020 22:00:34
#25 ]
Cult Member
Joined: 9-Mar-2003
Posts: 856
From: United Kingdom

@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 :)

 Status: Offline
Profile     Report this post  
ssolie 
Re: Autodoc replacement
Posted on 6-Jan-2020 22:28:12
#26 ]
Elite Member
Joined: 10-Mar-2003
Posts: 2747
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
Profile     Report this post  
ssolie 
Re: Autodoc replacement
Posted on 6-Jan-2020 22:30:03
#27 ]
Elite Member
Joined: 10-Mar-2003
Posts: 2747
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
Profile     Report this post  
ssolie 
Re: Autodoc replacement
Posted on 6-Jan-2020 22:33:36
#28 ]
Elite Member
Joined: 10-Mar-2003
Posts: 2747
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
Profile     Report this post  
ssolie 
Re: Autodoc replacement
Posted on 6-Jan-2020 22:36:37
#29 ]
Elite Member
Joined: 10-Mar-2003
Posts: 2747
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
Profile     Report this post  
Trixie 
Re: Autodoc replacement
Posted on 7-Jan-2020 7:13:54
#30 ]
Amiga Developer Team
Joined: 1-Sep-2003
Posts: 1939
From: Czech Republic

@ssolie, asymetrix

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

_________________
Smoke me a kipper, I'll be back for breakfast!

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
Profile     Report this post  
kolla 
Re: Autodoc replacement
Posted on 7-Jan-2020 7:46:17
#31 ]
Super Member
Joined: 21-Aug-2003
Posts: 1506
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
Profile     Report this post  
CygnusEd 
Re: Autodoc replacement
Posted on 7-Jan-2020 14:21:26
#32 ]
Regular Member
Joined: 7-Feb-2004
Posts: 384
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 pre, 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
Profile     Report this post  
CygnusEd 
Re: Autodoc replacement
Posted on 7-Jan-2020 14:24:45
#33 ]
Regular Member
Joined: 7-Feb-2004
Posts: 384
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 pre, 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
Profile     Report this post  
NutsAboutAmiga 
Re: Autodoc replacement
Posted on 7-Jan-2020 17:59:39
#34 ]
Elite Member
Joined: 9-Jun-2004
Posts: 11384
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
Profile     Report this post  
asymetrix 
Re: Autodoc replacement
Posted on 7-Jan-2020 21:11:01
#35 ]
Cult Member
Joined: 9-Mar-2003
Posts: 856
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
Profile     Report this post  
Goto page ( Previous Page 1 | 2 )

[ home ][ about us ][ privacy ] [ forums ][ classifieds ] [ links ][ news archive ] [ link to us ][ user account ]
Copyright (C) 2000 - 2019 Amigaworld.net.
Amigaworld.net was originally founded by David Doyle