Re: [Libclc-developers] Re: Suggested documentation format

[regis <re...@in...>]

Bertrand Mollinier Toublet wrote:
> 
> > From: Hallvard B Furuseth <h.b...@us...>
> >
> > Here is a suggestion for a file format for documentation.
> > Contributors should write this, though maybe the documentation
> > manager(s) will clean the file up a little, and it will be used to
> > generate the other formats. If accepted, I'll write a Perl program to
> > process it.  The overall documentation structure reflects Unix man
> > pages, as in <http://libclc.sourceforge.net/documentation-policy.txt>.
> > I've also added an initial NAME section.  (Bertrand, are you there?:-)
> >
> Yes, I am there... er... from time to time ;-)
> Sorry for the delay in replying...
> 
> > Format description:
> >
> <snipped>
> >
> Hallvard, thanks for the proposal, but...
> Thinking about the documentation issue, it appears that there is not
> likely going to be any *development* platform that doesn't also have
> HTML viewing support (e.g. the most hardcore command line Unix
> environment likely has Lynx). Thus, I'd like to think that the most
> practical format to publish our documentation is HTML. Of course there
> is a difference between what we published and what we archive, the
> former possibly being a processed version of the latter.
> 
> So, while I agree that the current format is certainly not adapted to
> our needs (and I should know, having "translated" all of the
> documentation so far from the text source to adequate HTML tagging), I
> don't think something slightly enhanced, but still close will be
> satisfying either.
> 
> I would like to try and come up with a general design for HTML version
> of our documentation. Once this is done, and approved, I could provide
> templates for the developers to fill out.
> 
> In the long run, we would like to come up with a more powerful tagging
> system (maybe somthing inspired from the DocBook format), from which we
> could produce a satisfying HTML version, why not a text version to be
> bundled with libclc releases, maybe also an alternate version of the
> documentation targeted at libclc developers rather than libclc users,
> etc.
> 
> > Questions:
> >
> <snip troff stuff>
> >
> > - Should manpage references in text, html and PostScript formats use
> >   the Unix format 'strcmp(3)', or just 'strcmp'?
> >
> Since we are not really producing any man-pages, merely a mimic of it, I
> think our references shall not include a man-section number.
> 


Can somebody recall me why the option of doxygen 
has been dropped while it produces html, man pages, and latex outputs?


-- 
Regis