Re: Documentation format for dak
Joerg Jaspert <joerg@debian.org> writes:
> 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?
As there are translations of DevRef around, it seems that some people
are interested in having localized documentation for developers. So
choosing one format that allows them to do this for the relevant
documentation in dak would be nice.
I only expect the "user" part of the documentation such as the
dak-commands syntax might get translated. The "admin" side of dak
should not need it.
>> 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?
Well, the question is do we want to keep that possibility open. And if
it ends up being the only deciding factor anyway...
Ansgar
Reply to: