Re: Switching apt documentation away from docbook
On Wed, Aug 21, 2019 at 06:42:09PM +0200, Julian Andres Klode wrote:
> APT's documentation is currently written in docbook. docbook
> is a huge XML mess that basically nobody can read or write,
> and it would be nice to replace it with something readable.
>
> # Contenders
>
> There are three file formats:
>
> - Markdown
> - reStructuredText
> - asciidoc
>
> None of them are perfect, all have problems.
>
> # Problems
>
> - We need to be able to reference common options and other
> stuff we have in apt.ent and apt-vendor.ent. I mean we
> can run a pre-processor on our files to substitute variables,
> it should not be a huge issue I guess (like we could just
> use XML entities I guess)
>
> - We do not want too many dependencies. Our contenders
> use Python or Haskell.
>
> - The guides: I don't think we actually need all the docbook
> guides we are shipping. The ones in apt-doc certainly could
> be folded into apt as manpages (the parts needed), and the
> ones in libapt-pkg-doc could be internal markdown files.
>
> - We lose all existing translations
Another thing to consider is that, optimally, we'd like to
have our files auto-formatted to avoid style conflicts. I guess
like pandoc can output the input format, so that might work.
--
debian developer - deb.li/jak | jak-linux.org - free software dev
ubuntu core developer i speak de, en
Reply to: