[erlang-bugs] Building docs for R13B-03 fails

[Sergei Golovan]

Hi again!

And another issue with Erlang manpages:

Erlang places manpages for its config files into section 4 and
application descriptions into section 6. Though man manual says that
section 4 is for "special files (usually found in /dev)" and section 6
is for "games" (?!).

I'd say that config files manpages are to be in section 5 "file
formats and conventions" and applications - in section 7 (just don't
fit any other section).

Would it be too hard to move manpages across sections (This will
require some minor changes to Erlang mode as well)? Or Erlang users
expect them in sections 4 and 6, so they couldn't find them elsewhere?

On Sat, Dec 19, 2009 at 11:58 PM, Sergei Golovan <sgolovan@REDACTED> wrote:
> Hi again!
>
> It seems that XSLT stylesheets which were used to generate Erlang
> R13B03 manpages are a bit buggy. The main problem is that in the
> generated manpages lines often start with dot (.) or apostrophe (').
> These characters start groff macros, so some info will be lost after
> manpage formatting.
>
> Also, tools like apropos don't understand the APPLICATION or MODULE
> sections and try to find the NAME one.
>
> Another minor bug is incorrect authors information formatting.
>
> The attached patch simply makes xsltproc add \& before all dot and
> apostrophe symbols, and replaces MODULE by NAME header, and adds some
> authors processing.
>
> To check for bugs the following command can be used:
> LANG=C MANWIDTH=80 man --warnings -l filename.3 >/dev/null
>
> On Mon, Dec 14, 2009 at 12:16 PM,  <lars@REDACTED> wrote:
>> Hi Sergei,
>> we started to build our documentation with open source tools in R13B03 so it
>> would be possible to build the doc from the delivered sources.
>>
>> But it's still only built in house because we hadn't time to test it but the plan is
>> to have it work for everyone in R13B04.
>>
>> Thanks for your report, we'll have a look at those fault.
>>
>> Regards Lars
>>
>>
>> Sergei Golovan wrote:
>>> Hi!
>>>
>>> I'm trying to build Erlang documentation from the sources (the goal is
>>> to switch from prebuilt docs for Debian Erlang packages as building
>>> them from the source is preferable).
>>>
>>> To do that I run
>>> make
>>> make TYPE=docs
>>> (in fact, make libs doesn't recognize TYPE, so I had to replace "make
>>> opt" by "make $(TYPE) in the top-level Makefile).
>>>
>>> and I've found several problems which make build fail:
>>>
>>> 1) For some XML files (e.g. erts/docs/src/book.xml) xsltproc reports
>>> runtime errors about undefined variables (partnum in line 871 and 963
>>> of db_pdf.xsl, in lines 1075 and 1173 of db_html.xsl). Is this a bug
>>> in the stylesheets or in xsltproc? (Both 1.1.24 from Debian stable and
>>> 1.1.26 from Debian unstable failed.)
>>>
>>> 2) wx application has duplicated targets html and docs in its makefile.
>>>
>>> 3) wx application (and others too) require docb_gen script to generate
>>> XML docs sources. It is missing. (I suppose that it is a simple
>>> wrapper around docb_gen Erlang module and could be recreated, but It'd
>>> be better if it were shipped in Erlang sources.)
>>>
>>> Is Erlang documentation supposed to be buildable from the source, or
>>> it still requires some unavailable tools?
>>>
>>> Cheers!
>>
>>
>
>
>
> --
> Sergei Golovan
>



-- 
Sergei Golovan