Mail #7848

Back to main page of archive

Previous mail   Next mail   Unformatted/full headers
Overview  10 days   Subject   Date   Thread   Author  

From: Grant Jacobs
Subject: Some observations [GHJ]
Date: 30 Jan 2003, 21:27:03

I thought this was moving over to gpc-doc? Should I send my postings 
which I've held back until sorting a hiccup registering for gpc-doc 
here instead?
(more below)

At 1:30 AM -0600 30/1/03, Richard D. Jackson wrote:
>On Tue, 2003-01-28 at 22:41, Frank Heckenbach wrote:
>  > Richard D. Jackson wrote:
[snip]

>What I envioson is more of a tag syntax verses a complete layout system.
>By tag I mean something that indicates that something is:
>Author name
>Module version
>copyright notice
>description
>return type/description ( may or may not need this )
>paramiter
>code example
>header ( by this I mean module header or description )
>referance
>index this for later cross referance
>ect...
>But not a whole lot of stuff. Leave formating and structure up to the
>output code. This is how POD, JavaDoc ( core stuff that is ) and a few
>others do. That way if you don't like the output you can write your own
>output generator that will format it the way you want. Core Doxygen does
>this as well but becasue the backend dictates the output form/layout it
>has had many output generaters created for it. But I think its down fall
>is that it does allow the programmer to use or embed form/layout stuff
>for specific output generaters which means the programmer spends can
>spend too much time trying to do some special form/layout verses just
>writing the doc. POD on the other had basicly has taken the stance that
>this is all you get and if you don't like it write your own output
>module to get what you want. This means that it has sacrificed
>flexablity for conformance to a standard. And do you know something Perl
>code is some of the best documented code out there. Which is why I want
>to follow the perl lead but mostlikly not the format itself. Mostly
>becase POD does contain some format/layout command in it as well. I
>really don't want to worry about format/layout when I document code.
>
>What I intend to do before writing any code is to write a specification
>which I will run by here for comments before writing any code. As I
>would rather have input and some kind of agrement that it is what we
>want.

Sounds as if we have been thinking along similar lines. I have my own 
with notes somewhere on my system...

I agree with leaving formatting to later. You could generate XML and 
then downstream users could use CSS for layout, for example.

Don't include format per se, but include some style class information 
like 'header' 'text' etc so that it can be appropriately formatted 
later.

[big snip; us documentation types write a bit... :-) !]

>First the question I would have is what is the target application of the
>documenter? If for only documenting single monolithic units then a
>single pass ( single file ) tool would do the job. But on the other hand
>if you want to handle multi-module/unit applications that need to beable
>to cross link the documention and or have a unified cross-referance
>amogst all the code modules then what you really want to do is process
>all of the files in a single pass. And for doing this OOP will be very
>helpfull.
>One other thing I would like for it to do besides output the
>documentation is to output a cross referance list so that other modules
>can referance the doc if needed.
>For instance lets say I'm writing a string utility unit wouldn't it be
>nice if I could referance the RTS with in my doc's and actualy have a
>working link to the RTS doc for a paricular function/procedure verses
>something like this " see these functions in the RTS documentation
>....."

Its a good point, but I think processing all the files in a single 
pass has exactly the same flaw as compiling code in the same fashion. 
The interface/implementation approach was developed for that reason. 
I have some thoughts about this, but perhaps they make the doc 
application too complex for an initial version, so I'll hold off for 
now.

Grant

Previous mail   Next mail   Unformatted/full headers
Overview  10 days   Subject   Date   Thread   Author  

Replies

In reply to

Back to main page of archive

Note: This page contains information that does not originate from the owner of this web site, but from the authors of the mails archived. The owner of this web site is not responsible for the content of such information. Any use of that infomation requires the consent of the respective author.

Where WWW addresses (URLs) in the mails archived are marked as hyperlinks, this is only for the comfort of the reader. The content of the web pages linked to like this does not necessarily reflect the opinion of the owner of this web site or of the authors of the mails archived. The owner of this web site is not responsible for the content of such web pages. Those pages are explicitly not to be considered as part of the content of this page, but merely as references.

This page was created by Crystal 0.999 (Linux 2.4.27/i686).