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

[Matt Kangas]

Kenneth,

Thank you for the prompt and very detailed response! I apologize if my  
questions seemed to come out of nowhere. I'm a new user of Erlang,  
just getting used to what tools & resources are available.

(Longer response sent direct - will bring discussion back to the list  
if anyone's interested)

Thanks,
--Matt

On Feb 11, 2008, at 6:08 PM, Kenneth Lundin wrote:

> 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

-- 
Matt Kangas
kangas@REDACTED – www.p16blog.com