Docbook: Documentation toolchain documentation updates.
Move some of the documentation about documentation toolchain itself from docbook/README.adoc to the documentation toolchain chapter in the WSDG. Fix the Debugger section level. Change-Id: I8db92d334dd479324453f7b0bd25b33ea770c532 Reviewed-on: https://code.wireshark.org/review/36843 Reviewed-by: Gerald Combs <gerald@wireshark.org> Petri-Dish: Gerald Combs <gerald@wireshark.org> Tested-by: Petri Dish Buildbot Reviewed-by: Anders Broman <a.broman58@gmail.com>
This commit is contained in:
Gerald Combs
Anders Broman
parent
2bdff1df49
commit
e9e90f67b7
|
|
@ -1,3 +1,5 @@
|
|||
|
||||
:experimental:
|
||||
= Introduction
|
||||
|
||||
This directory contains the source files needed to build the:
|
||||
|
|
@ -15,54 +17,11 @@ The guides and release notes are written in
|
|||
https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor syntax].
|
||||
For more information see https://asciidoctor.org.
|
||||
|
||||
Conversions from Asciidoctor markup to each of our supported output
|
||||
formats is done via the following steps:
|
||||
|
||||
- HTML: Asciidoctor → DocBook XML → xsltproc + DocBook XSL
|
||||
- Chunked HTML: Asciidoctor → DocBook XML → xsltproc + DocBook XSL
|
||||
- PDF: Asciidoctor
|
||||
- HTMLHelp: Asciidoctor → DocBook XML → xsltproc + DocBook XSL → HHC
|
||||
- Text: [HTML output] → elinks
|
||||
|
||||
= Requirements
|
||||
|
||||
Ultimately we'd like to reduce the toolchain requirements to AsciidoctorJ
|
||||
alone, but that's not yet possible. Additional tooling is required for
|
||||
the HTML and HTMLHelp targets. See the Developer's Guide for instructions
|
||||
on installing required packages for your platform.
|
||||
|
||||
== AsciidoctorJ (recommended) or Asciidoctor
|
||||
|
||||
Text markup format and publishing toolchain:
|
||||
https://asciidoctor.org/
|
||||
|
||||
AsciidoctorJ is a self-contained bundle which includes Asciidoctor and
|
||||
JRuby. It can be installed via Chocolatey on Windows, Homebrew on macOS,
|
||||
or a .zip extraction anywhere
|
||||
(https://bintray.com/asciidoctor/maven/asciidoctorj).
|
||||
|
||||
== DocBook XML and XSL
|
||||
|
||||
Converting from DocBook to HTML and CHM requires the DocBook DTD
|
||||
(http://www.sagehill.net/docbookxsl/ToolsSetup.html) and DocBook
|
||||
stylesheets
|
||||
(http://www.sagehill.net/docbookxsl/InstallStylesheets.html).
|
||||
These are available via installable packages on most Linux distributions,
|
||||
and Homebrew.
|
||||
|
||||
== xsltproc
|
||||
|
||||
http://xmlsoft.org/xslt/[xsltproc] converts DocBook XML to various
|
||||
formats based on XSL stylesheets. It either ships as part of the
|
||||
operating system or is available via an installable package on
|
||||
most Linux distributions.
|
||||
|
||||
== HTML Help Workshop (Windows only)
|
||||
|
||||
The HTML Help compiler is part of the
|
||||
https://www.microsoft.com/en-us/download/details.aspx?id=21138[HTML Help Workshop]
|
||||
from Microsoft. It is used to generate the documentation shipped with
|
||||
the Windows installers.
|
||||
Ultimately we'd like to reduce the toolchain requirements to AsciidoctorJ alone, but that's not yet possible.
|
||||
Additional tooling is required for the HTML and HTMLHelp targets.
|
||||
See the https://www.wireshark.org/docs/wsdg_html_chunked/ChToolsDocumentationToolchain.html[Developer's Guide] for instructions on installing required packages for your platform.
|
||||
|
||||
= Asciidoctor Markup
|
||||
|
||||
|
|
@ -79,7 +38,7 @@ Please use the following conventions when writing documentation:
|
|||
- Use Asciidoctor macros for buttons, keys, and menus. Note that these
|
||||
are currently experimental:
|
||||
|
||||
** The button:[Start] button
|
||||
** The btn:[Start] button
|
||||
** Press kbd:[Shift+Ctrl+P] to open the preferences dialog.
|
||||
** Select menu:File[Open] from the main menu.
|
||||
|
||||
|
|
|
|||
|
|
@ -455,6 +455,9 @@ Asciidoctor markup.
|
|||
Our various output formats are generated using the following tools.
|
||||
Intermediate formats are in _italics_.
|
||||
|
||||
Man page roff:: pod2man
|
||||
Man page HTML:: pod2html
|
||||
|
||||
Guide HTML:: Asciidoctor → _DocBook XML_ → xsltproc + DocBook XSL
|
||||
Guide PDF:: Asciidoctor
|
||||
Guide HTML Help:: Asciidoctor → _DocBook XML_ → xsltproc + DocBook XSL → HHC
|
||||
|
|
@ -470,21 +473,25 @@ JavaScript (Asciidoctor.js). Only the Asciidoctor and AsciidoctorJ
|
|||
flavors are supported for building the Wireshark documentation and
|
||||
AsciidoctorJ is recommended.
|
||||
|
||||
The guides and release notes were originally written in DocBook (hence
|
||||
the directory name). They were later converted to AsciiDoc and then
|
||||
migrated to Asciidoctor.
|
||||
https://asciidoctor.org/docs/migration/[`compat-mode`] is currently
|
||||
enabled for the guides, but we are steadily migrating to Asciidoctor’s
|
||||
modern (>= 1.5.0) syntax.
|
||||
The guides and release notes were originally written in DocBook (hence the directory name).
|
||||
They were later converted to AsciiDoc and then migrated to Asciidoctor.
|
||||
We currently use Asciidoctor’s modern (>= 1.5.0) syntax.
|
||||
|
||||
PDF output requires Asciidoctor PDF. It is included with AsciidoctorJ
|
||||
but _not_ with Asciidoctor.
|
||||
|
||||
==== Xsltproc And DocBook
|
||||
==== DocBook XML and XSL
|
||||
|
||||
The single HTML, chunked HTML, and HTML Help guides are generated using
|
||||
DocBook XSL stylesheets. They in turn require an XSLT processor. We use
|
||||
`xsltproc`.
|
||||
Converting from DocBook to HTML and CHM requires the DocBook DTD
|
||||
(http://www.sagehill.net/docbookxsl/ToolsSetup.html) and DocBook
|
||||
stylesheets
|
||||
(http://www.sagehill.net/docbookxsl/InstallStylesheets.html).
|
||||
These are available via installable packages on most Linux distributions, Chocolatey, and Homebrew.
|
||||
|
||||
==== xsltproc
|
||||
|
||||
http://xmlsoft.org/xslt/[xsltproc] converts DocBook XML to various formats based on XSL stylesheets.
|
||||
It either ships as part of the operating system or is available via an installable package on most Linux distributions, Chocolatey, and Homebrew.
|
||||
|
||||
==== HTML Help
|
||||
|
||||
|
|
@ -507,7 +514,7 @@ since 2002).
|
|||
|
||||
[[ChToolsDebugger]]
|
||||
|
||||
==== Debugger
|
||||
=== Debugger
|
||||
|
||||
Using a good debugger can save you a lot of development time.
|
||||
|
||||
|
|
@ -516,7 +523,7 @@ otherwise the debugger will simply fail or you will only see a lot of garbage.
|
|||
|
||||
[[ChToolsMSVCDebugger]]
|
||||
|
||||
===== Visual Studio Integrated Debugger
|
||||
==== Visual Studio Integrated Debugger
|
||||
|
||||
You can use the integrated debugger of Visual Studio if your toolchain includes
|
||||
it. Open the solution in your build directory and build and debug as normal
|
||||
|
|
@ -559,7 +566,7 @@ If you require a non-optimised version, then build using a debug configuration.
|
|||
|
||||
[[ChToolsMSDebuggingTools]]
|
||||
|
||||
===== Debugging Tools For Windows
|
||||
==== Debugging Tools For Windows
|
||||
|
||||
You can also use the Microsoft Debugging Tools for Windows toolkit, which is a
|
||||
standalone GUI debugger. Although it’s not that comfortable compared to
|
||||
|
|
|
|||
Loading…
Reference in New Issue