diff options
author | Gerald Combs <gerald@wireshark.org> | 2016-08-22 15:10:24 -0700 |
---|---|---|
committer | Gerald Combs <gerald@wireshark.org> | 2016-08-22 23:57:14 +0000 |
commit | 943a9ede85962f07fc75b64e2ed12bdc54a911bb (patch) | |
tree | 728f72f6ea137231639767a12bddfe0aa880908a /docbook | |
parent | 9c80ff0617a67d9f024f11d0dbd7943a76f69bc6 (diff) |
Update docbook/README.txt
Update to reflect current reality. Still needs a lot of work.
Change-Id: Id6bb12f5e8ca42bbadc237f148bb388b54a321e2
Reviewed-on: https://code.wireshark.org/review/17247
Reviewed-by: Gerald Combs <gerald@wireshark.org>
Diffstat (limited to 'docbook')
-rw-r--r-- | docbook/README.txt | 88 |
1 files changed, 21 insertions, 67 deletions
diff --git a/docbook/README.txt b/docbook/README.txt index 863b1fd515..83664ffc41 100644 --- a/docbook/README.txt +++ b/docbook/README.txt @@ -1,3 +1,5 @@ += Introduction = + This directory contains the source files needed to build the: - Wireshark User's guide @@ -5,12 +7,13 @@ This directory contains the source files needed to build the: - Release notes (NEWS) - Lua Reference +To build everything, just run `make` (for Windows see README.cmake). +Requirements are listed below. -To build everything, just do 'make' (for Win32: see README.cmake) -but see the requirements below. - -The guides are written in Docbook/XML (formerly Docbook/SGML). The release -notes are written in AsciiDoc (http://asciidoc.org/). +The guides and release notes are written in AsciiDoc (http://asciidoc.org), +but use many Asciidoctor (http://asciidoctor.org/) markup extensions which +are provided in asciidoctor-asciidoc.conf. The documentation toolchain may +switch exclusively to Asciidoctor at some point in the future. To get HTML, PDF or other output formats, conversions are done using XSL stylesheets, which provides a flexible way for these conversions. @@ -21,6 +24,11 @@ formats and two PDF's. Requirements: ------------- +AsciiDoc +-------- +Text documentation format and conversion suite: +http://asciidoc.org/ + DocBook XML DTD --------------- DocBook "official" XML DTD V4.5: @@ -60,12 +68,13 @@ http://offo.sourceforge.net/hyphenation/. Different pattern files have different licenses. The English patterns may have restrictions on commercial use. -AsciiDoc --------- -Text documentation format and conversion suite: http://asciidoc.org/. AsciiDoc -can use either w3m (default) or Lynx for plain text output. We use AsciiDoc for -the Developer's Guide, User's Guide, and for the release notes. Lynx is used to -render the official plaintext release announcements. + +AsciiDoc Notes +-------------- + +AsciiDoc can use either w3m (default) or Lynx for plain text output. We use +AsciiDoc for the Developer's Guide, User's Guide, and for the release notes. +Lynx is used to render the official plaintext release announcements. The AsciiDoc files have been converted from DocBook. In a lot of cases the markup is wrong, inconsistent, or both. Use the following markup conventions @@ -100,7 +109,7 @@ many (especially in a row) are distracting and annoying. Lynx ---- Text based web browser which can convert HTML to plain text. -(Alternative [*nix]: elinks) +(Alternatives: w3m and elinks) dblatex ------- @@ -235,58 +244,3 @@ Using the prefix wsdg_ instead of wsug_ will build the same targets but for the Wireshark Developer's Guide. The makefile is written to be run with make on UNIX/Linux platforms. - - -Notes to authors ----------------- -The docbook DTD provides you with all tags required to mark up a documents -structure. Please have a look at the existing XML files to see what these -structural tags are, and look at the DocBook web references below. -To maintain a consistent look and feel in the documents please use the -following tags for the indicated purposes. - -Tag Purpose ---- ------- -<application> to mark application names, like Wireshark. -<filename> to mark an individual file or path. -<command> to mark a command, with parameters. -<prompt> to mark a prompt before user input. -<userinput> to mark an example of user input, like an actual command line. -<function> to mark a function name, ending with parenthesis. -<parameter> to mark (function) parameters. -<varname> to mark (environment) variables. -<literal> to mark some literal value. - -These are all tags for inline text. Wrap literal text output in a CDATA block, -like so: - - <programlisting> -<![CDATA[#include <epan/tap.h> -... -]]> - </programlisting> - -Make sure the CDATA clause is at column 1, because prefixed whitespace will be -present in the verbatim output as well. - - -Docbook web references: ------------------------ -Some web references to further documentation about Docbook/XML and Docbook XSL -conversions: - -DocBook: The Definitive Guide -by Norman Walsh and Leonard Muellner -http://www.docbook.org/tdg/en/html/docbook.html - -DocBook XSL: The Complete Guide -by Bob Stayton -http://www.sagehill.net/docbookxsl/index.html - -Documention with DocBook on Win32 -by Jim Crafton -http://www.codeproject.com/KB/winhelp/docbook_howto.aspx - -FO Parameter Reference -by Norman Walsh -http://docbook.sourceforge.net/release/xsl/current/doc/fo/ |