2020-04-14 18:49:04 +00:00
:experimental:
Switch from AsciiDoc to Asciidoctor.
Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.
The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:
HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC
This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:
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
Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.
The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.
Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.
Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
2017-10-19 22:03:55 +00:00
= Introduction
2016-08-22 22:10:24 +00:00
2004-08-06 21:06:27 +00:00
This directory contains the source files needed to build the:
Switch from AsciiDoc to Asciidoctor.
Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.
The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:
HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC
This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:
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
Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.
The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.
Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.
Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
2017-10-19 22:03:55 +00:00
- Wireshark User’ s Guide
- Wireshark Developer’ s Guide
- Release notes (NEWS)
- Lua Reference
2004-08-06 21:06:27 +00:00
Switch from AsciiDoc to Asciidoctor.
Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.
The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:
HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC
This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:
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
Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.
The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.
Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.
Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
2017-10-19 22:03:55 +00:00
To build everything, build the `all_guides` target, e.g. `ninja
all_guides` or `msbuild all_guides.vcxproj`. Requirements are listed
below.
2004-08-06 21:06:27 +00:00
Switch from AsciiDoc to Asciidoctor.
Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.
The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:
HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC
This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:
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
Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.
The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.
Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.
Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
2017-10-19 22:03:55 +00:00
The guides and release notes are written in
2019-07-20 15:13:59 +00:00
https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor syntax].
For more information see https://asciidoctor.org.
2004-08-06 21:06:27 +00:00
2021-06-18 10:20:51 +00:00
== Requirements
2004-08-06 21:06:27 +00:00
2020-04-14 18:49:04 +00:00
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.
2014-08-18 16:31:26 +00:00
2021-06-18 10:20:51 +00:00
== Asciidoctor Markup
2014-08-18 16:31:26 +00:00
Switch from AsciiDoc to Asciidoctor.
Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.
The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:
HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC
This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:
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
Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.
The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.
Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.
Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
2017-10-19 22:03:55 +00:00
The User’ s and Developer’ s Guides were originally written in DocBook and
2019-07-20 15:13:59 +00:00
were later converted to https://asciidoc.org/[AsciiDoc]. We subsequently
Switch from AsciiDoc to Asciidoctor.
Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.
The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:
HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC
This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:
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
Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.
The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.
Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.
Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
2017-10-19 22:03:55 +00:00
switched from AsciiDoc to Asciidoctor. As a result we currently use
2019-07-20 15:13:59 +00:00
https://asciidoctor.org/docs/migration/[compat mode], but may switch
Switch from AsciiDoc to Asciidoctor.
Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.
The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:
HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC
This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:
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
Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.
The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.
Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.
Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
2017-10-19 22:03:55 +00:00
to Asciidoctor’ s modern markup at a later date.
2014-08-18 16:31:26 +00:00
Switch from AsciiDoc to Asciidoctor.
Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.
The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:
HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC
This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:
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
Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.
The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.
Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.
Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
2017-10-19 22:03:55 +00:00
Please use the following conventions when writing documentation:
2014-08-18 16:31:26 +00:00
Switch from AsciiDoc to Asciidoctor.
Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.
The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:
HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC
This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:
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
Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.
The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.
Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.
Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
2017-10-19 22:03:55 +00:00
- Window and dialog box names should be in “curly quotes”.
2014-08-18 16:31:26 +00:00
Switch from AsciiDoc to Asciidoctor.
Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.
The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:
HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC
This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:
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
Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.
The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.
Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.
Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
2017-10-19 22:03:55 +00:00
- Use Asciidoctor macros for buttons, keys, and menus. Note that these
are currently experimental:
2020-04-14 18:49:04 +00:00
** The btn:[Start] button
2018-05-31 18:14:27 +00:00
** Press kbd:[Shift+Ctrl+P] to open the preferences dialog.
** Select menu:File[Open] from the main menu.
Switch from AsciiDoc to Asciidoctor.
Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.
The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:
HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC
This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:
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
Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.
The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.
Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.
Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
2017-10-19 22:03:55 +00:00
This ensures that UI elements are shown consistently and lets us apply styles
to each type of element.
2014-08-18 16:31:26 +00:00
Switch from AsciiDoc to Asciidoctor.
Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.
The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:
HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC
This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:
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
Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.
The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.
Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.
Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
2017-10-19 22:03:55 +00:00
- Command line examples should reflect the OS:
+
2014-08-18 16:31:26 +00:00
----
$ echo Linux and UNIX
----
2018-05-31 18:14:27 +00:00
+
2014-08-18 16:31:26 +00:00
----
C:\> echo Windows
----
2022-02-08 04:58:52 +00:00
Admonitions ([NOTE], [TIP], [IMPORTANT], [CAUTION] and [WARNING]) can be used to highlight important
2014-08-18 16:31:26 +00:00
information. Keep in mind that they interrupt the flow of text by design. Too
many (especially in a row) are distracting and annoying.
2021-06-18 10:20:51 +00:00
== Custom Asciidoctor Macros
The following custom macros are available in `docbook/asciidoctor-macros`:
commaize-block::
Sorts a list of items and separates them with commas with an "and" preceding the last item.
cveidlink-inline-macro::
Links a CVE ID to cve.mitre.org.
manarg-block::
Ensures that individual arguments don't wrap in order to improve readability.
wsbuglink-inline-macro::
Links an issue number to gitlab.org/wireshark/wireshark/-/issues.
wssalink-inline-macro::
Links a security advisory to www.wireshark.org.
2018-05-31 18:14:27 +00:00
== Asciidoctor Live Preview
The Asciidoctor project provides a JavaScript version of Asciidoctor
(asciidoctor.js), which enables live previews in many web browsers and
text editors. See the
https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/[Live
Preview] documentation for more information.
Note that our documentation depends on attributes defined in
2019-02-14 23:23:05 +00:00
_attributes.adoc_. The User’ s Guide and Developer’ s Guide are split
across several files, and only the top-level _user-guide.adoc_ and
_developer-guide.adoc_ include _attributes.adoc_. As a result,
2018-05-31 18:14:27 +00:00
some markup will be incomplete. You can work around this somewhat by
adding some attributes such as `compat-mode experimental` to your Live
Preview settings.
Switch from AsciiDoc to Asciidoctor.
Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.
The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:
HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC
This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:
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
Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.
The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.
Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.
Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
2017-10-19 22:03:55 +00:00
= HTML Help Alternatives
2004-08-06 21:06:27 +00:00
Switch from AsciiDoc to Asciidoctor.
Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.
The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:
HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC
This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:
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
Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.
The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.
Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.
Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
2017-10-19 22:03:55 +00:00
Ideally we would ship documentation with Wireshark that is pleasant to
read, browsable, and searchable. Unfortunately we don't have an easy way
to do this. The closest we've been able to come is by shipping an HTML
Help (.chm) file on Windows. However, HTML Help a) is limited to Windows,
b) crusty on normal displays, and c) really crusty on HiDPI displays.
The following alternative formats are available, each with advantages
and disadvantages:
== WebHelp
https://en.wikipedia.org/wiki/Web_help[WebHelp] has three main
dependencies:
- DocBook XSL, including...
- webhelpindexer.jar
- The user's local web browser
This format generates both HTML pages and JavaScript, which might not run
reliably on end user machines.
== PDF
2007-02-03 04:09:22 +00:00
Switch from AsciiDoc to Asciidoctor.
Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.
The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:
HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC
This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:
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
Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.
The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.
Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.
Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
2017-10-19 22:03:55 +00:00
PDF output is page oriented, with static page sizes. This _usually_ isn't
a problem with modern reader software. However it doesn't look like we
can reliably load a PDF file and jump to specific section on some
platforms. For example, loading +++file:///path/to/user_guide.pdf#location+++
works in Firefox & Chrome, but not in Safari, Preview, or Internet Explorer.
2013-03-15 21:18:16 +00:00
Switch from AsciiDoc to Asciidoctor.
Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.
The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:
HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC
This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:
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
Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.
The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.
Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.
Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
2017-10-19 22:03:55 +00:00
== Qt Help
2019-07-20 15:13:59 +00:00
Qt provides an extensive https://doc.qt.io/qt-5/qthelp-framework.html[help system].
Switch from AsciiDoc to Asciidoctor.
Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.
The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:
HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC
This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:
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
Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.
The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.
Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.
Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
2017-10-19 22:03:55 +00:00
However, to use it we need to generate a Qt Help Project (.qhp) file,
which isn't currently supported by Asciidoctor or via DocBook XSL.
The default help application (Qt Assistant) is ugly. We'd probably want
to write our own help viewer app or integrate help directly via
QHelpEngine.