[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Documentation format for dak

On 13042 March 1977, Ansgar Burchardt wrote:

> The format should support output to HTML and man and support translations.

HTML sure, man ok, but what the heck do we need translation support for
in dak?

> I do like human-readable formats so suggest going with either AsciiDoc
> or Sphinx.  From a quick glance at two random documents[2][3], I find
> the AsciiDoc syntax a bit nicer, however using Sphinx might allow us to
> use the same format for API and other documentation (should we decide to
> switch from epydoc).

You know, seeing how much people are keeping the api doc up2date (only
when forced), do you really think it makes sense to switch that around?

> Are there any other formats to consider or other things to think of? Do
> you already have some experience with any of these formats?

I'm a big fan of org-mode, dislike docbook and am not sure if asciidoc
or sphinx is better, should we go to one of them.

> Org-mode:
>   Emacs.
>   Output formats: HTML, LaTeX, man and others.
>     Not sure about man, but it was said it's possible on IRC.
>   Not sure about translation support.

It definitely does man too.

bye, Joerg
Kids, kids. I’m not going to die. That only happens to bad people.

Reply to: