how to build Documentation/DocBook/

[Jim Davis]

On Fri, Jul 17, 2015 at 6:18 AM, Luis de Bethencourt
<luis at debethencourt.com> wrote:
>
> On 17 July 2015 at 13:40, Ahmed Soliman <ahmedsoliman0x666 at gmail.com> wrote:
>>
>> I have fresh kernel downloaded by git and I want to know how to build
>> Documentation/DocBook/ as pdf I have tried
>> make pdfdocs >output
>> but I got those warnings
>> Warning(.//include/linux/init.h): no structured comments found
>> Warning(.//kernel/sys.c): no structured comments found
>> Warning(.//drivers/dma-buf/seqno-fence.c): no structured comments found
>> Warning(.//drivers/dma-buf/reservation.c): no structured comments found
>> Warning(.//include/linux/reservation.h): no structured comments found
>> Warning(.//include/linux/hsi/hsi.h:150): Excess
>> struct/union/enum/typedef member 'e_handler' description in
>> 'hsi_client'
>> Warning(.//include/linux/hsi/hsi.h:150): Excess
>> struct/union/enum/typedef member 'pclaimed' description in
>> 'hsi_client'
>> Warning(.//include/linux/hsi/hsi.h:150): Excess
>> struct/union/enum/typedef member 'nb' description in 'hsi_client'
>> make[1]: *** [Documentation/DocBook/kernel-hacking.pdf] Error 9
>> make: *** [pdfdocs] Error 2
>>
>> and the file output look like this
>>
>
> Which Kernel version are you using? It looks like your error has been fixed
> by:
> https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=9e39dc1e563e8d390bae42ee80e1e665c18b7de2
>
> Unfortunately. make pdfdocs fails when building DocBook/scsi.pdf in the
> latest stable release (4.1.2)

I've been trying to run make pdfdocs with the 4.2-rc3 tree, on Arch
Linux, Fedora 22, and Ubuntu 15.04.  A plain 'make pdfdocs' fails on
all of them.

For Arch and Fedora, I've gotten a little further by installing
dblatex (which isn't a default package) and running the ungainly
command

make POSTARGS='--verbose --debug' POSTPOSTARGS='--verbose --debug'
XMLTOFLAGS='-vv -m Documentation/DocBook/stylesheet.xsl
--skip-validation --with-dblatex' pdfdocs

but while that chugged through several books, it failed with

pdflatex -interaction=batchmode filesystems.tex
pdflatex failed
filesystems.tex:9322: Paragraph ended before \@citex was complete.
filesystems.tex:9325: Too many }'s.
filesystems.tex:9325: leading text:       }
filesystems.tex:9328: Paragraph ended before \@citex was complete.
filesystems.tex:9331: Too many }'s.
filesystems.tex:9331: leading text:        }

and examining the generated TeX file, it does look like a paragraph problem:

\label{see_also}\hyperlabel{see_also}%

  \cite{

                Journaling the Linux ext2fs Filesystem, LinuxExpo 98, Stephen T$

          }

  \cite{

                Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen Tweedie

           }

After fiddling with Documentation/DocBook/filesystems.tmpl to squish
some newlines,

diff --git a/Documentation/DocBook/filesystems.tmpl
b/Documentation/DocBook/filesystems.tmpl
index bcdfdb9a92770..44a0afe5bfb72 100644
--- a/Documentation/DocBook/filesystems.tmpl
+++ b/Documentation/DocBook/filesystems.tmpl
@@ -385,18 +385,12 @@ an example.
     <sect1 id="see_also">
      <title>See also</title>
     <para>
-      <citation>
-       <ulink url="http://kernel.org/pub/linux/kernel/people/sct/ext3/journal-design.ps.gz">
-           Journaling the Linux ext2fs Filesystem, LinuxExpo 98,
Stephen Tweedie
-       </ulink>
-      </citation>
+      <citation><ulink
url="http://kernel.org/pub/linux/kernel/people/sct/ext3/journal-design.ps.gz">
+           Journaling the Linux ext2fs Filesystem, LinuxExpo 98,
Stephen Tweedie</ulink></citation>
     </para>
     <para>
-       <citation>
-       <ulink url="http://olstrans.sourceforge.net/release/OLS2000-ext3/OLS2000-ext3.html">
-           Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen Tweedie
-       </ulink>
-       </citation>
+       <citation><ulink
url="http://olstrans.sourceforge.net/release/OLS2000-ext3/OLS2000-ext3.html">
+           Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen
Tweedie</ulink></citation>
     </para>
     </sect1>

filesystems.pdf built, but...

pdflatex -interaction=batchmode drm.tex
pdflatex failed
drm.tex:18707: Illegal unit of measure (pt inserted).
drm.tex:18707: leading text: \setlength{\tabcolsep}{0}
drm.tex:18710: Package array Error: Empty preamble: `l' used.
drm.tex:18710: leading text: \begin{tabular}{}

so again there's some sort of bogus TeX being generated, and this time
I didn't see an obvious fix.

Jim