Re: autogsdoc questions and suggestions

[Stefan Urbanek]

On 2003-07-22 06:54:01 +0200 Richard Frith-Macdonald <richard@brainstorm.co.uk> 
wrote:

> On Tuesday, July 22, 2003, at 12:25 AM, Stefan Urbanek wrote:
>
> > hi,
> >
> > I have a few questions concerning autogsdoc. First of all, I think it  is a 
> > nice tool. Besides that, I was not able to find some readable and  clean 
> > examples about how to use that tool.
> >
> > QUESTIONS
> >
> > 1. How can I use CSS with HTML files generated by autogsdoc?
> > 2. I have several frameworks:
> >       /SourceRoot
> >           /Documentation
> >           /Frameworks
> >               /Framework1
> >               /Framework2
> >               ....
> > How can I make top level documentation .html file containing  references to all 
> > frameworks, and how can put it into GNUmakefile?  Somtehing like 'suite 
> > contents'.
>
> Ideally, you should be able to use a .gsdoc file together with the  -Projects 
> flag for autogsdoc to tell it how to find the projects you  want to link to.  
> However, the prjref element needed to refer to an  external project as a whole 
> is not implemented, so you would have to  link to individual classes (or use a 
> global scope index).

How can i create/usr global scope index?

<snip>

> > 4. How can I tell autogsdoc to move authors and date to the bottom of  the page?
> > 5. Where should I put templates for such directory layout if they are common 
> > for all frameworks, except names?
> > 6. How can I specify a template for class documentation? I do not want 
> > Contents, Authors and 'Software documentation for ...' title. The  title is not 
> > necessary, because I already know that i am looking at  class documentation. 
> > What i want is only a class name, description,  declared in/conforms to, method 
> > index and method descriptions.
> >
> > Maybe more questions comming soon.
>
> I think there is pretty much a single answer to most of the above  really ... 
> autogsdoc does not have any customisability built in ... it  was written 
> primarily to generate gnustep-base documentation, and while  it's still a good 
> tool for documenting any other ObjC code, you get the  same presentation that 
> the base library gets.

Would it be possible to change it to some more generic objc documentation tool? 
I think it has almost everything that is needed for separate tool. Just some 
customisation is missing.

> That being said, you have two options ...
>
> a. Change autogsdoc to do what you want ... eg. provide a new version  of the 
> AGSHtml.m source, rewrittten to use some form of templates.  Any  nicely 
> designed, generic approach which produces something like the  current output as 
> default would probably be welcome.

I know, that is the point behind open source, however ... to be able to modify 
it i need to learn internals of autogsdoc, learn xml, learn autogsdoc html 
output, and more. I have no time.

> b. Post-process the outupt ... since the output is currently xhtml, you  can 
> use an xslt tool to transform it any way you want,
> though you could of course use other text manipulation tools.  This  might need a minor 
> tweak to AGSHtml.m to get it to output the  appropriate <?xml version...> and 
> <!DOCTYPE ...> header/wrapper info  for stricter xslt tools.

hm, another tool. same as above - no time for that if i want to focus on the 
real stuff :o/


> > SUGGESTIONS
> >
> > I think that autogsdoc should strictly differentiate between pure  class 
> > documentation and some generic documentation (like text in  chapters).
> I'm not sure what you mean by that.  The base library documentation has  
> generic documentation in
> Documentation/Base.gsdoc.  Are you saying there should be generic  
> documentation and class documentation in the same file?

No, the opposite. I am saying that autogsdoc (or some of its functionality) 
should generate ONLY class documentation. Perhaps some autogsdoc clone, that 
just takes .[hm] files and creates nothing more and nothing less thatn pure 
class/protocol/category/method documentation.

> > What do you think about using code from DevelopmentKit in Autogsdoc? 
> > http://savannah.nongnu.org/projects/develkit/ (see examples in Testing 
> > directory)

<snip>

> I'm very much against using external software (however good) ... I  don't want 
> to need to link against
> anything that might not be installed.   I wanted it to be possible to  build 
> gnustep-base completely
> in one go.

I understand and agree here with you.

> I mean, you download it and run 'make install' and everything is done,  rather 
> than -
> download base, build and install library
> download another library, build and install,
> build and install autogsdoc and documentation
>
> I know it's only a small thing, but I'd like it to be as easy as  possible for 
> a new user to get everything
> they need installed.

i think that creating a documentation is not task for user, but for developer. 
developer should provide documentation within software package or as standalone 
package. user should be freed from this task. Therefore having some separate 
tool (if autogsdoc were in a standalone package) is not a problem, because 
developer is more experienced.

Stefan
--
http://urbanek.host.sk

First they ignore you, then they laugh at you, then they fight you, then you 
win.
- Mahatma Gandhi