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

[Hallvard B F. <h.b...@us...>]

Bertrand Mollinier Toublet writes:
> 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.

Sigh.  Just like me to suggest the format and forget to mention _why_ I
suggested it.

The idea was

* to have one source format for documentation from which a script would
  produce the "real" documentation: at least HTML, text and Unix man
  format.  Similar to doxygen, I take it.  I'd like us to make the
  documentation available in at least these formats.  After that,
  PostScript documentation can be generated with groff from the manpages
  for those who are interested.  For that matter, I think the text
  format can too.

* A simple enough source format that contributors can write it even if
  they have no special tools like doxygen, and which should be easy
  for the documentation manager(s) to edit to fix any problem in
  the contributed text.  That way there will be no need to translate
  contributed documentation to doxygen.

> 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'm not quite sure what you mean here.  My format can be translated to
Unix-manpage-like HTML pages, with links to other the HTML pages
documenting other CLC functions.  Is that insufficient?

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

I think it's a very bad idea to request people to write HTML
documentation.  Experience shows that this will give us a lot of bad
HTML, unless the documentation manager(s) takes on the job of cleaning
it up and validating it.  Even then, cleanup can be a lot of work.
Besides, we can't generate Unix manpages from HTML.

> In the long run, we would like to come up with a more powerful tagging
> system (maybe somthing inspired from the DocBook format),

I don't know that one.

> maybe also an alternate version of the documentation targeted at
> libclc developers rather than libclc users, etc.

Hmm.  I'm not sure what that part would say, at least not something
which fit in the user documentation.  If it's about the implementation
of a module, it belongs in the source code, not in the user
documentation.  The latter should not change if the implementation
changes.

-- 
Hallvard