docbook/README.txt

   1 = Introduction =
   2
   3 This directory contains the source files needed to build the:
   4
   5  - Wireshark User's guide
   6  - Wireshark Developer's Guide
   7  - Release notes (NEWS)
   8  - Lua Reference
   9
  10 To build everything, just run `make` (for Windows see README.cmake).
  11 Requirements are listed below.
  12
  13 The guides and release notes are written in AsciiDoc (http://asciidoc.org),
  14 but use many Asciidoctor (http://asciidoctor.org/) markup extensions which
  15 are provided in asciidoctor-asciidoc.conf. The documentation toolchain may
  16 switch exclusively to Asciidoctor at some point in the future. See the
  17 AsciiDoctor section at the end of this document for details.
  18
  19 To get HTML, PDF or other output formats, conversions are done using XSL
  20 stylesheets, which provides a flexible way for these conversions.
  21
  22 By default the Makefile generates HTML in single page and multiple (chunked)
  23 formats and two PDF's.
  24
  25 Requirements:
  26 -------------
  27
  28 AsciiDoc
  29 --------
  30 Text documentation format and conversion suite:
  31 http://asciidoc.org/
  32
  33 DocBook XML DTD
  34 ---------------
  35 DocBook "official" XML DTD V4.5:
  36 http://www.oasis-open.org/docbook/xml/
  37 (available as a package for Linux / Cygwin)
  38
  39 DocBook XSL
  40 -----------
  41 The "official" XSL stylesheets from Norman Walsh:
  42 http://docbook.sourceforge.net/
  43 (available as a package for Linux / Cygwin)
  44
  45 xsltproc
  46 --------
  47 The XSL processor xsltproc. Part of libxslt:
  48 http://xmlsoft.org/xslt/
  49 Available as a package for Linux / Cygwin.
  50 Supplied with Mac OS X Panther and later.
  51
  52 FOP processor (for PDF generation only)
  53 ---------------------------------------
  54 FOP processor from the apache project:
  55 http://xml.apache.org/fop/
  56
  57 FOP is a Java program, so you need to have a Java environment installed.
  58 The makefiles look for fop-2.1 in the docbook directory. You can change
  59 this location by setting the FOP environment variable.
  60
  61 FOP might return an OutOfMemoryException. You can limit its memory usage
  62 by adding " -Xmx256m" to the FOP_OPTS environment variable. The Windows
  63 makefile does this by default.
  64
  65 Hyphenation Patterns
  66 --------------------
  67 Hyphenation patterns for FOP can be found at
  68 http://offo.sourceforge.net/hyphenation/. Different pattern files have
  69 different licenses. The English patterns may have restrictions on
  70 commercial use.
  71
  72
  73 AsciiDoc Notes
  74 --------------
  75
  76 AsciiDoc can use either w3m (default) or Lynx for plain text output. We use
  77 AsciiDoc for the Developer's Guide, User's Guide, and for the release notes.
  78 Lynx is used to render the official plaintext release announcements.
  79
  80 The AsciiDoc files have been converted from DocBook. In a lot of cases the
  81 markup is wrong, inconsistent, or both. Use the following markup conventions
  82 for any new or revised text:
  83
  84 - Window and dialog box names should be in ``curly quotes''.
  85
  86 - Use Asciidoctor compatibility macros for buttons, keys, and menus:
  87
  88   The button:[Start] button
  89   Press kbd:[Shift+Ctrl+P] to open the preferences dialog.
  90   Select menu:File[Open] from the main menu.
  91
  92   This ensures that UI elements are shown consistently and lets us apply styles
  93   to each type of element.
  94
  95 - Command line examples should reflect the OS:
  96
  97 ----
  98 $ echo Linux and UNIX
  99 ----
 100
 101 ----
 102 C:\> echo Windows
 103 ----
 104
 105 Admonitions ([NOTE], [TIP], and [WARNING]) can be used to highlight important
 106 information. Keep in mind that they interrupt the flow of text by design. Too
 107 many (especially in a row) are distracting and annoying.
 108
 109
 110 Lynx
 111 ----
 112 Text based web browser which can convert HTML to plain text.
 113 (Alternatives: w3m and elinks)
 114
 115 dblatex
 116 -------
 117 DocBook to LaTeX converter. Required for AsciiDoc PDF conversion on Win32.
 118
 119 Win32 only: HTML help compiler (for .chm generation only)
 120 ---------------------------------------------------------
 121 HTML Help Compiler (hhc.exe) from Microsoft:
 122 http://www.microsoft.com/en-us/download/details.aspx?id=21138
 123
 124 Packages for Win32
 125 ------------------
 126 Installing the asciidoc package will pull in almost all the other required Cygwin packages.
 127 You may need to run "build-docbook-catalog" from a Cygwin bash prompt in order to register your catalog properly.
 128
 129 Tool/File           Cygwin Package          Opt./Mand.  Comments
 130 ---------           --------------          ----------  --------
 131 asciidoc            Doc/asciidoc            M           cygwin python is a dependency and will also be installed (if not installed)
 132 xsltproc:           Libs/libxslt            M
 133 xsl stylesheets:    Text/docbook-xsl        M           docbook.xsl, chunk.xsl and htmlhelp.xsl
 134 docbookx.dtd:       Text/docbook-xml42      M           a later version may be required (e.g. Doc/docbook-xml45), depending on your asciidoc installation
 135 docbookx.dtd:       Text/docbook-xml45      M           current asciidoc installations require this
 136 lynx:               Web/lynx                M
 137 dblatex             Text/dblatex            O           A number of dependencies will also be installed
 138 fop:                -                       O           URL: http://xml.apache.org/fop/ - install it into docbok\fop-1.x or wireshark_lib_dir\fop-1.x
 139 hhc:                -                       O           URL: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
 140 zip:                Archive/zip             O
 141 getopt:             Base/util-linux         O           Required to run "build-docbook-catalog"
 142
 143
 144 Packages for Suse 9.3
 145 ---------------------
 146 Tool/File           Package                 Opt./Mand.  Comments
 147 ---------           -------                 ----------  --------
 148 xsltproc:           libxslt                 M
 149 xsl stylesheets:    docbook-xsl-stylesheets M           docbook.xsl and chunk.xsl
 150 docbookx.dtd:       docbook_4               M
 151 fop:                fop                     O
 152
 153
 154 Packages for Gentoo
 155 -------------------
 156 Like with all packages do ...
 157 Check dependencies: emerge -p <package>
 158 Install it:         emerge <package>
 159
 160 Tool/File           Package                  Opt./Mand.   Comments
 161 ---------           -------                  ----------   --------
 162 xsltproc:           libxslt                  M
 163 xsl stylesheets:    docbook-xsl-stylesheets  M            docbook.xsl and chunk.xsl
 164                                                           Necessary docbook catalogs are built automatically by portage in /etc/xml and /etc/sgml
 165                                                             docbook.xsl and chunk.xsl using "/usr/bin/build-docbook-catalog".
 166                                                             So docbook runs out of the box on Gentoo.
 167 docbookx.dtd:       docbook-xml-dtd          M
 168 fop:                fop                      O            Has a lot of JAVA dependencies.
 169 Quanta+             quanta or kdewebdev      O            Nice HTML/XML/SGML and Docbook editor with Syntaxhighlighting, Autocompletion, etc.
 170
 171 Tip: The actual DTD version of Gentoo is 4.4, but wireshark docs still use 4.2.
 172      To be able to generate the docs, change the version in the second line of
 173      developer-guide.xml or install an older version of the DTD.
 174      See into the Gentoo handbook howto unmask old versions.
 175
 176
 177 Packages for Fedora
 178 -------------------
 179 Tool/File           Package                 Opt./Mand.  Comments
 180 ---------           -------                 ----------  --------
 181 xsltproc:           libxslt                 M
 182 xsl stylesheets:    docbook-style-xsl       M           docbook.xsl and chunk.xsl
 183 docbookx.dtd:       docbook-dtds            M           provides v4.1, v4.2, v4.3, v4.4 DTDs
 184 asciidoc:           ascidoc                 M
 185
 186 fop:                fop                     O           See above
 187
 188 Note: There are required dependencies (such as xml-common and sgml-common);
 189       yum is your friend for doing package installs including required
 190       dependencies.
 191
 192
 193 Packages for Debian
 194 -------------------
 195 Tool/File           Package                 Opt./Mand.  Comments
 196 ---------           -------                 ----------  --------
 197 xsltproc:           libxslt                 M
 198 xsl stylesheets:    docbook-xsl             M
 199 chunk.xsl:          docbook-xsl             M
 200 htmlhelp.xsl:       docbook-xsl             M
 201 docbookx.dtd:       docbook-xml             M
 202 fop:                fop                     O           See above
 203
 204
 205
 206 Makefile:
 207 --------------------------
 208 There are several ways and tools to do these conversion, following is a short
 209 description of the way the makefile targets are doing things and which output
 210 files required for a release in that format.
 211
 212 all
 213 Will generate both guides in all available output formats (see below).
 214
 215 make wsug
 216 Will generate Wireshark User's Guide in all available output formats.
 217
 218 make wsug_html
 219 The HTML file is generated using xsltproc and the XSL stylesheets from
 220 Norman Walsh. This is a conversion into a single HTML page.
 221 output: wsug_html
 222
 223 make wsug_html_chunked
 224 The HTML files are generated using xsltproc and the XSL stylesheets from
 225 Norman Walsh. This is a conversion into chunked (multiple) HTML pages.
 226 output: wsug_html_chunked
 227
 228 make wsug_pdf_us
 229 make wsug_pdf_a4
 230 The PDF is generated using an intermediate format named XSL-FO (XSL
 231 formatting objects). xsltproc converts the XML to a FO file, and then FOP
 232 (Apache's formatting object processor) is used to generate the PDF document,
 233 in US letter or A4 paper format.
 234 Tip: You will get lot's of INFO/WARNING/ERROR messages when generating PDF,
 235 but the conversion works just fine.
 236 output: user-guide-us.pdf user-guide-a4.pdf
 237
 238 make wsug_chm
 239 On Win32 platforms, the "famous" HTML help format can be generated by using a
 240 special HTML chunked conversion and then use the htmlhelp compiler from
 241 Microsoft.
 242 output: htmlhelp.chm
 243
 244 Using the prefix wsdg_ instead of wsug_ will build the same targets but for the
 245 Wireshark Developer's Guide.
 246
 247 The makefile is written to be run with make on UNIX/Linux platforms.
 248
 249 AsciiDoctor
 250 -----------
 251
 252 At the time of this writing (November 2016) the AsciiDoctor project is much
 253 more active than AsciiDoc. At some point it might be worth the effort to
 254 migrate to AsciiDoctor. To do so we'd have to do the following at a minimum:
 255
 256 - Require Ruby + AsciiDoctor or Java + AsciiDoctorj to build the documentation.
 257
 258 - Either port the macros in asciidoc.conf to AsciiDoctor or stop using them.
 259
 260 - Restrict ourselves to decimal entities since the PDF renderer doesn't
 261   support hexadecimal ones:
 262   https://github.com/asciidoctor/asciidoctorj/issues/439
 263
 264 - Choose a "compat" mode: http://asciidoctor.org/docs/migration/