Click Here
home features news forums classifieds faqs links search
6071 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
24 crawler(s) on-line.
 146 guest(s) on-line.
 0 member(s) on-line.



You are an anonymous user.
Register Now!
 miggymac:  27 mins ago
 Gunnar:  55 mins ago
 pixie:  2 hrs 16 mins ago
 DiscreetFX:  2 hrs 55 mins ago
 DWolfman:  3 hrs 4 mins ago
 cncparts:  4 hrs 38 mins ago
 saipaman4366:  5 hrs 24 mins ago
 Beajar:  5 hrs 43 mins ago
 Rob:  5 hrs 46 mins ago
 agami:  6 hrs 49 mins ago

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

Goto page ( 1 | 2 Next Page )
PosterThread
ssolie 
Autodoc replacement
Posted on 4-Jan-2020 19:11:56
#1 ]
Elite Member
Joined: 10-Mar-2003
Posts: 2755
From: Alberta, Canada

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.

Here are a couple of ideas:
https://en.wikipedia.org/wiki/Comparison_of_documentation_generators


Maybe the answer is to just add markup to Autodoc and extend it a bit.

_________________
ExecSG Team Lead

 Status: Offline
Profile     Report this post  
NutsAboutAmiga 
Re: Autodoc replacement
Posted on 4-Jan-2020 20:31:00
#2 ]
Elite Member
Joined: 9-Jun-2004
Posts: 12795
From: Norway

@ssolie

I think it be great to have it online, and I think it has to place where you can upload docs, so have place to find any docs we need.

its also useful to have it offline.

Really hate when the server goes down, or the site its hosted on don't work anymore
so mirror sites if its online service be great.

It be great if can sync documents locally, maybe a de centralized service?

Should be future safe, so we don’t need new web browser, or run into other issues.

Last edited by NutsAboutAmiga on 04-Jan-2020 at 08:37 PM.
Last edited by NutsAboutAmiga on 04-Jan-2020 at 08:36 PM.
Last edited by NutsAboutAmiga on 04-Jan-2020 at 08:34 PM.

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

 Status: Offline
Profile     Report this post  
Trixie 
Re: Autodoc replacement
Posted on 4-Jan-2020 21:02:53
#3 ]
Amiga Developer Team
Joined: 1-Sep-2003
Posts: 2089
From: Czech Republic

@ssolie

Quote:
Maybe the answer is to just add markup to Autodoc and extend it a bit.

Would be perfectly fine by me. And the existing tools could relatively easily be adapted to that.

_________________
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
Profile     Report this post  
asymetrix 
Re: Autodoc replacement
Posted on 4-Jan-2020 23:35:13
#4 ]
Cult Member
Joined: 9-Mar-2003
Posts: 868
From: United Kingdom

@thread

I dont think AmigaOS API has a DOM yet.

Autodoc 'replacement' the name itself has imposed limits.

If one is to write a tool - dont make just something that does one thing only and that is it, if a developer has gone through the trouble - at least create it in such a way that others can reuse it in the future.
The text parser alone can be a library on its own, extendable to support other languages, or reused in a text formatting program for example.

I do think some sort of rule based system has to be in place - to check complience of the API.

How will the data be used ? visually or passed on to other software for analysis ?

Humans probably want markup or html, other software would want JSON.

Can a change in the API change all the documentation at once ?

Maybe a mini git could be used so that developers can add realtime converstational comments to codeblocks at source.

Cross reference with documentation online, offline, notes, patchs you name it.

Depends how far do you want to go ?

For example an online markup software solution could be in high demand from other developers as a free service and a paid service for companies that need more storage space.

If you want to develop faster without restarting hardware then a Hypervisor is required - usable to all Amigoid systems, a central platform / API for all.

You may need a dedicated team.





_________________
Download 499.26 Mbps, 659.94 Mbps Upload :)

 Status: Offline
Profile     Report this post  
Jose 
Re: Autodoc replacement
Posted on 5-Jan-2020 1:43:23
#5 ]
Cult Member
Joined: 10-Mar-2003
Posts: 992
From: Unknown

Sounds like a total waste of time and money, I thought you guys were out of resources ?
Anyway, yeah, I like the idea of extending it, but why mark up. BTW wasn't there a security risk with this in that some version allowed executables or something, can't remember well...

Last edited by Jose on 05-Jan-2020 at 01:48 AM.

_________________

José

 Status: Offline
Profile     Report this post  
khayoz 
Re: Autodoc replacement
Posted on 5-Jan-2020 1:58:23
#6 ]
Regular Member
Joined: 26-Dec-2004
Posts: 216
From: Stockholm, Sweden

@ssolie

Did a cross post at Amigans.net - https://www.amigans.net/modules/xforum/viewtopic.php?forum=3&topic_id=8136&post_id=116793#forumpost116793
Edit: Over there is where you should be at and ask these kinda questions.


Edit: By the link you shared I would say stay with Autodoc and lay the power on ExegSG ;)
Otherwise Robodoc, Headerdoc when looking at language support.

Last edited by khayoz on 05-Jan-2020 at 02:21 AM.
Last edited by khayoz on 05-Jan-2020 at 02:06 AM.

_________________

 Status: Offline
Profile     Report this post  
Trixie 
Re: Autodoc replacement
Posted on 5-Jan-2020 7:03:22
#7 ]
Amiga Developer Team
Joined: 1-Sep-2003
Posts: 2089
From: Czech Republic

@Jose

Quote:
Sounds like a total waste of time and money

Quality documentation is key to cutting down on development time, as well as to acquiring new developers.

Quote:
but why mark up

Because with standardized mark-up you can identify certain types of information in the document (such as function synopses, parameters and results). Documentation viewers can then parse this information easily and present it in a way that allows finding it quickly.

Quote:
wasn't there a security risk with this in that some version allowed executables or something, can't remember well...

That was AmigaGuide, not Autodoc.

_________________
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
Profile     Report this post  
walkero 
Re: Autodoc replacement
Posted on 5-Jan-2020 13:56:13
#8 ]
Regular Member
Joined: 4-Mar-2004
Posts: 396
From: Athens

@ssolie

I am not sure I understand what you describe.

You are looking to replace the autodocs with an other format? If so, then a lot of current Amiga apps that handle autodocs are going to become obsolete.

Are you looking a cross platform Autodoc viewer? If so, have you checked the Apignosis (https://bitbucket.org/walkero/apignosis/wiki/Home)? It works on Windows, Linux and Mac OS and since I develop it, we can cooperate on making it more useful, if you want.

_________________
Amiga-Look.org - Beautify your Workbench

 Status: Offline
Profile     Report this post  
cgutjahr 
Re: Autodoc replacement
Posted on 5-Jan-2020 14:39:26
#9 ]
Cult Member
Joined: 8-Mar-2003
Posts: 969
From: Unknown

ssolie is no longer working for the actual AmigaOS developer, is he? Not sure his opinion on what API documentation AmigaOS should use has more weight than Franko's...

 Status: Offline
Profile     Report this post  
NutsAboutAmiga 
Re: Autodoc replacement
Posted on 5-Jan-2020 14:54:58
#10 ]
Elite Member
Joined: 9-Jun-2004
Posts: 12795
From: Norway

@cgutjahr

As defense agents Amiga Inc, Hyperion declared that ExecSG belonged to contractor “Hans Jurgen Frieden” as he was not fully compensated, as Hyperion can’t pay for the work being / was done, then "Hans Jurgen Frieden" sold it to private person “Robert Trevor Dickinson”, so I guess ExecSG is now a new company of its own.

SSolie contract was terminated with Hyperion, but he got new job working for ExecSG team, as team coordinator.

So now you have 3 companies that has some thing to say in development of AmigaOS4.x, you have AEON, then you have ExecSG team, and you have Hyperion Entertainment CVBA, and other sub-contractors working other parts like RoadShow that is own product (so not part of AmigaOS3.1.4), Hyperion is now owner of Reaction, so that can now be integrated into AmigaOS 3.2.

Last edited by NutsAboutAmiga on 05-Jan-2020 at 03:35 PM.
Last edited by NutsAboutAmiga on 05-Jan-2020 at 03:03 PM.
Last edited by NutsAboutAmiga on 05-Jan-2020 at 02:56 PM.
Last edited by NutsAboutAmiga on 05-Jan-2020 at 02:55 PM.

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

 Status: Offline
Profile     Report this post  
Amigo1 
Re: Autodoc replacement
Posted on 5-Jan-2020 15:10:44
#11 ]
Super Member
Joined: 24-Jun-2004
Posts: 1582
From: the Clouds

@NutsAboutAmiga

Quote:

NutsAboutAmiga wrote:
@cgutjahr

As defense agents Amiga Inc, Hyperion declared that ExecSG belonged to contractor “Hans Jurgen Frieden” as he was not fully compensated, as Hyperion can’t pay for the working being done, then "Hans Jurgen Frieden" sold it to private person “Robert Trevor Dickinson”, so I guess ExecSG is now a new company of its own.

ssolie contract was terminated with Hyperion, but he got new job working for ExecSG team, as team coordinator.

So now you have 3 companies that has some thing to say in development of AmigaOS4.x, you have AEON, then you have ExecSG team, and you have Hyperion Entertainment CVBA, and other sub-contractors working other parts like RoadShow that is own product (so not part of AmigaOS3.1.4), Hyperion is now owner of Reaction, so that can now be integrated into AmigaOS 3.2.


A Boing Ball has about 72 checkered fields, about about 68 entities missing to make the Amiga whole again!

Last edited by Amigo1 on 05-Jan-2020 at 03:11 PM.

 Status: Offline
Profile     Report this post  
Trixie 
Re: Autodoc replacement
Posted on 5-Jan-2020 15:27:42
#12 ]
Amiga Developer Team
Joined: 1-Sep-2003
Posts: 2089
From: Czech Republic

@cgutjahr

Quote:
Not sure his opinion on what API documentation AmigaOS should use has more weight than Franko's

Considering that he works on ExecSG, which is a core AmigaOS component, surely he has a say? But if you believe that a key developer's opinion equals that of a random forum nonentity, more power to you.

Last edited by Trixie on 05-Jan-2020 at 03:28 PM.

_________________
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
Profile     Report this post  
OldFart 
Re: Autodoc replacement
Posted on 5-Jan-2020 15:35:59
#13 ]
Elite Member
Joined: 12-Sep-2004
Posts: 3059
From: Stad; en d'r is moar ain stad en da's Stad. Makkelk zat!

@ssolie

A good question you ask here! Browsing the current OS-4 AutoDocs, I can tell you I find it quite a nightmare! Not in anywhich way can it show some userfriendlyness.
Sure, the first page goes fine with a list of all libraries and clicking one of the entries surely gives you the entire AutoDocs available for that library. But then any hint of userfriendlyness stops dead as one is greeted with a full list of all functionnames available in said library, immediately followed with the name of the first available function in alphabetical sense. Which is followed by the next, and so on and so forth.

I've often wondered whether it would be a viable option to turn the "Table of Contents" into some arrangement of a list with clickable names leading to the page with the AutoDocs for that particular function. Every function its own private 'page'. This makes the AutoDocs far more accessible.

The "Table of contents" (= ToC) could be augmented with the currently available Version.Revision numbers and every entry in the ToC could be augmented with the Version.Revision numbering reflecting the state of its developent and whether a function is N(ew), U(pdated) or O(bsolete).

In the AutoDocs of a certain selected function, make it clear (very clear!) which option is available from which Version.Revision.

Also, when it comes to the section of "SEE ALSO": make every entry clickable (if applicable, which is actually always...) and present that particular page.

And finally, in case of "EXAMPLES": make some room for third-parties entries, keeping in mind that the entries have to be tested by the author (and maybe again by some "official" Autodoc Example Code Tester).

I'm glad you brought the issue up.

Have a good and prosperous 2020 (hex for 2 spaces, btw...)!

OldFart

_________________
More then three levels of indigestion and you're scroomed!

 Status: Offline
Profile     Report this post  
bison 
Re: Autodoc replacement
Posted on 5-Jan-2020 15:42:28
#14 ]
Elite Member
Joined: 18-Dec-2007
Posts: 2112
From: N-Space

@Trixie

Quote:
Quality documentation is key to cutting down on development time, as well as to acquiring new developers.

Indeed it is! I started a job in 1996 where all the original developers had left the company, and the online "documentation" consisted of a GIF of a nuclear explosion.

_________________
"Unix is supposed to fix that." -- Jay Miner

 Status: Offline
Profile     Report this post  
TRIPOS 
Re: Autodoc replacement
Posted on 5-Jan-2020 19:09:27
#15 ]
Super Member
Joined: 4-Apr-2014
Posts: 1204
From: Unknown

@Trixie

Quote:

Trixie wrote:
@cgutjahr

Quote:
Not sure his opinion on what API documentation AmigaOS should use has more weight than Franko's

Considering that he works on ExecSG, which is a core AmigaOS component, surely he has a say? But if you believe that a key developer's opinion equals that of a random forum nonentity, more power to you.


If you have missed that Hyperion's single goal over the last 20 years has been to gather and bring "Amiga OS" and associated IP under their own control, then I'm afraid you have been completely blind for two decades. Everything (every single thing!) they have done, has been in line with their striving to achieve that goal. Cgutjahr's comment is perfectly valid, the only reason to why ExecSG is still part of OS4 is because Hyperion hasn't released a new version of OS4 without it. Yet. But it sure as hell makes sense for them to do so because AeonKit taking key components of OS4 out of Hyperion's hands and control damages Hyperion's (perceived) IP portfolio, thus risking completely nullifying their entire struggle for the last 20 years. Wait and watch it happen. You'll see.




@NutsAboutAmiga

Quote:

NutsAboutAmiga wrote:

So now you have 3 companies that has some thing to say in development of AmigaOS4.x, you have AEON, then you have ExecSG team, and you have Hyperion Entertainment CVBA, and other sub-contractors working other parts like RoadShow that is own product (so not part of AmigaOS3.1.4)


You have AeonKit and Hyperion. And then you also have the Cloanto sphere, the owner of the Amiga OS and the copyrights that OS4 depends upon (they will probably form a new company called "Amiga Corporation" or whatever within a year or so).

Sub-contractors? Not so many these days...


Quote:
Hyperion is now owner of Reaction, so that can now be integrated into AmigaOS 3.2.


That would possibly be more heretical than replacing the rainbow checkmark with a boing ball in the Kickstart boot screen for absolutely no reason, and it would definitely be a step towards turning the 68k OS into the Frankenstein abomination they already created with OS4. What would the next step be? Introducing incompatibility by introducing the OS4 libraries model for no reason? Or replacing the autodocs?

Not that it's their decision to make...

 Status: Offline
Profile     Report this post  
sTix 
Re: Autodoc replacement
Posted on 5-Jan-2020 19:11:09
#16 ]
Regular Member
Joined: 22-Oct-2003
Posts: 138
From: Lund, Sweden

@ssolie

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.

_________________

 Status: Offline
Profile     Report this post  
NutsAboutAmiga 
Re: Autodoc replacement
Posted on 5-Jan-2020 20:42:04
#17 ]
Elite Member
Joined: 9-Jun-2004
Posts: 12795
From: Norway

@TRIPOS

No no "Cloanto" only own the names and logos and so on, and they have none exclusive license to use. They also have right to C64 roms as it turns out, found something about that, some wont make new C64 but Clonato did respond to the request..

Now this was back in 2009.

https://eab.abime.net/showthread.php?t=46109

So people think that Cloanto is interested in unify the community and so on, they are not. They are interesting in preserving and controlling the assets, so the only source is Amiga forever emulation package. if you lucky it ends up history museum whit non edit lienee, like it happened with Electronics Arts Deluxe Paint.

Last edited by NutsAboutAmiga on 05-Jan-2020 at 08:44 PM.

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

 Status: Offline
Profile     Report this post  
NutsAboutAmiga 
Re: Autodoc replacement
Posted on 5-Jan-2020 20:48:44
#18 ]
Elite Member
Joined: 9-Jun-2004
Posts: 12795
From: Norway

@TRIPOS

During the development of AmigaOS4.0, Amiga Inc and Hyperion signed a buy back agreement, where the assets to AmigaOS source code transferred exclusively to Hyperion to develop AmigaOS4.x, if Amiga Inc did go bankrupt the asset be transferred back to Amiga Inc, sadly for Amiga Inc they did go bankrupt and had to create new companies to make it look like they did not go bankrupt, remember Amiga India, and Amiga Delver, contract work was not payed in full as well, Hyperion work on AmigaDE and AmigaOS4.x and was compensated for AmigaDE work, but not fully for AmigaOS4.x work as I understand it, as result Hyperion had recap there investment by selling AmigaOS on their own.

That did go down well with Amiga Inc so fight in legal system, it ended in selttelemt agreement that gave Hyperion more right to use some logos and names and so on, and non compete agreement with Amiga Inc.

One argument made was it as impossible to transferee the assets back to Amiga Inc, because contractors where not fully compensated, until they where compensated they owned the components they had worked on, as result Exec Sg ended up in the hands of “Hans-Jörg Frieden"

Later Amiga Inc made deal with Commodore USA, to make a computer called C64 and Amiga running CommodoreOS, its a bit strange to me that agreement went down, did Amiga Inc own the Commodore name? Do I remember correct... but as Amiga Inc can't compete whit Hyperion, Commodore USA had to use Linux.

Last edited by NutsAboutAmiga on 05-Jan-2020 at 09:09 PM.
Last edited by NutsAboutAmiga on 05-Jan-2020 at 09:08 PM.
Last edited by NutsAboutAmiga on 05-Jan-2020 at 09:02 PM.
Last edited by NutsAboutAmiga on 05-Jan-2020 at 09:01 PM.
Last edited by NutsAboutAmiga on 05-Jan-2020 at 08:57 PM.
Last edited by NutsAboutAmiga on 05-Jan-2020 at 08:55 PM.
Last edited by NutsAboutAmiga on 05-Jan-2020 at 08:49 PM.

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

 Status: Offline
Profile     Report this post  
number6 
Re: Autodoc replacement
Posted on 5-Jan-2020 21:34:36
#19 ]
Elite Member
Joined: 25-Mar-2005
Posts: 11540
From: In the village

@NutsAboutAmiga

Quote:
Later Amiga Inc made deal with Commodore USA, to make a computer called C64 and Amiga running CommodoreOS, its a bit strange to me that agreement went down, did Amiga Inc own the Commodore name? Do I remember correct.


No, sorry. Barry was dealing with Asiarim for the Commodore licensing. Shortly thereafter Asiarim's licensing arm was declared bankrupt and the licenses to both CUSA and Manomio were terminated.

Any negotiation with Bill McEwen was for the rights to brand Barry's "Amiga" branded products.

Barry's post about the new owners

Barry's post about the re-negotiated agreement with Amiga Inc.

the product

discussion with Ben

More prior page of same thread.

#6

Last edited by number6 on 05-Jan-2020 at 09:35 PM.

_________________
This posting, in its entirety, represents solely the perspective of the author.
*Secrecy has served us so well*

 Status: Offline
Profile     Report this post  
CygnusEd 
Re: Autodoc replacement
Posted on 5-Jan-2020 23:36:05
#20 ]
Regular Member
Joined: 7-Feb-2004
Posts: 393
From: germany

@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.

_________________
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
Profile     Report this post  
Goto page ( 1 | 2 Next Page )

[ 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