[Libclc-developers] Re: Suggested documentation format

[Bertrand M. T. <ber...@en...>]

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

--
Bertrand