[erlang-questions] Documentation build process: creating DocBook XML?

[Kenneth Lundin]

On 2/11/08, Matt Kangas <kangas@REDACTED> wrote:
> Dear Erlang team, and erlang-questions readers,
>
> I have some questions about the Erlang *documentation* build process.
> I'll list my questions first, then explain my reasons for asking...
>
> Questions:
>
> 1) What makefile targets are used to build the HTML documentation from
> source?
The makefiles for building the documentation is not part of the source tar ball.

> Given an Erlang source tarball, can I build all of http://www.erlang.org/doc/
>  myself?
No, since the sources for the documentation is not included.
As said earlier we are preparing for making the doc sources (in XML) available.
It will happen soon (most probably before summer).
>
> 2) Which tools are used to generate which parts of the documentation?
> I've discovered "docbuilder" and "edoc" so far. What else gets called
> by make to crank out the doc tree?
docbuilder is used to build all html except the top page and some
index files which are built with specific Erlang programs currently
not part of the distribution.

Some applications are documented with edoc which is then translated to
xml, fed into docbuilder to get the same format for everything.

>
> 3) What module(s) would I have to hack in order to add another output
> format to the documentation generator? Any advice on how to start? :-)
docbuilder and the generated html is undergoing stepwise improvements right now.
There is a lot of history in docbuilder since the documentation source
was in SGML. Much of this history makes docbuilder more complicated
than it need to be and we will improve that stepwise.
Docbuilder is the only code you need to hack to add another output format.
It would be relatively easy to add a new output format in parallell
with xhtml which
is the current format.

There are currently 3 backends for docbuilder: html, man, pdf (via latex)
Only the html backend is included in the distribution.
The man-backend is not released since we don't think it is so
important. Only the reference manuals for modules and cprograms can be
translated to man.
The pdf backend is not released since it is dependent on a number of
external tools. If we could handle all the conversion to pdf in Erlang
we would distribute that backend as well.

The generated html can be used as passive files , there is no need for
a web-server
which can deliver active content, this has been a principle from the
beginning and it is still relevant.

>
>
> Motivation:
>
> I'd like to see if put together an "improved" version of the current
> docs: same content, better presentation. Specifically, I'd like to try
> putting the Erlang docs inside the PHP documentation framework, as
> outlined here:
>
> http://www.p16blog.com/p16/2008/02/user-added-comm.html
>
> DocBook XML is the format I'd need to generate. It's a popular doc-
> source format for open-source projects, so even if PHP's framework
> proves unsuitable, several other doc frameworks should be directly
> usable.
I am well aware of DocBook it is a huge DTD. The possibility to use
existing backends for docbook to generate html and pdf could be
interesting.
But when I searched around for such backends a year or two ago I did not find
anything that was attractive enough.

I followed the link above to the PHP doc and I was not impressed by
the format. The idea with
notes from readers is nice but would't a type of Wiki be nicer?
What else is so much better in the php doc's format?

The notes from readers would be interesting to implement, but it would
require some active logic on the server side, which we don't need
today.
But it would be relatively easy to implement even from scratch without
use of the
PHP framework. Have to read the PHP doc how to.
>
> If I make any progress, I'll gladly contribute all code back to the
> community. :-)

If there is a specific output format we can agree on I am interested
in making a backend for it.
Until then I will continue the improvements on the docbuilder html
backend, considering the suggestions regarding google friendly etc.

/Kenneth Erlang/OTP team at Ericsson
>
> Thanks in advance,
> --Matt Kangas
>
> --
> Matt Kangas
> kangas@REDACTED – www.p16blog.com
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://www.erlang.org/mailman/listinfo/erlang-questions
>