1berry/wireshark
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
wireshark/doc/README.documentation.adoc

96 lines
3.2 KiB
Plaintext
Raw Normal View History

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>
2020-04-14 11:49:04 -07: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 15:03:55 -07:00
= Introduction
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>
2016-08-22 15:10:24 -07:00
Svn stuff: - Add eol-style native to all text files - Add Id attributes Add $Id: $ to all text files Makefile: - add several files and directories to make clean - Add comments for values on Suse 9.1 catalog.xml: - Add comments for values on Suse 9.1 svn path=/trunk/; revision=11618
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 15:03:55 -07:00
- Wireshark User’s Guide
- Wireshark Developer’s Guide
- Release notes (NEWS)
- Lua Reference
Svn stuff: - Add eol-style native to all text files - Add Id attributes Add $Id: $ to all text files Makefile: - add several files and directories to make clean - Add comments for values on Suse 9.1 catalog.xml: - Add comments for values on Suse 9.1 svn path=/trunk/; revision=11618
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 15:03:55 -07:00
To build everything, build the `all_guides` target, e.g. `ninja
all_guides` or `msbuild all_guides.vcxproj`. Requirements are listed
below.
Svn stuff: - Add eol-style native to all text files - Add Id attributes Add $Id: $ to all text files Makefile: - add several files and directories to make clean - Add comments for values on Suse 9.1 catalog.xml: - Add comments for values on Suse 9.1 svn path=/trunk/; revision=11618
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 15:03:55 -07:00
The guides and release notes are written in
Documentation: convert http URLS to https Remove some dead links or point them to archive.org while at it. All updated links have been verified. Change-Id: Icf02167a13d5fe9dfce39ea57525b3f185554c9d Reviewed-on: https://code.wireshark.org/review/34028 Petri-Dish: Peter Wu <peter@lekensteyn.nl> Tested-by: Petri Dish Buildbot Reviewed-by: Anders Broman <a.broman58@gmail.com>
2019-07-20 16:13:59 +01:00
https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor syntax].
For more information see https://asciidoctor.org.
Svn stuff: - Add eol-style native to all text files - Add Id attributes Add $Id: $ to all text files Makefile: - add several files and directories to make clean - Add comments for values on Suse 9.1 catalog.xml: - Add comments for values on Suse 9.1 svn path=/trunk/; revision=11618
2004-08-06 21:06:27 +00:00
Docs+Packaging: Convert our man pages to Asciidoctor. Convert doc/*.pod to Asciidoctor. This: * Means we use the same markup for our man pages, the guides, and release notes. * Lets us add versions to our man pages. * Gives us more formatting options, e.g. AsciiDoc supports `commands`, nested lists and makes it easy to include version information. The manpage backend doesn't seem to support tables very well, unfortunately. Convert our CMake configuration to produce *roff and html man pages using Asciidoctor. Add a "manarg" block macro which makes our synopses wrap correctly. Similar to the release notes, guides, and FAQ, if Asciidoctor isn't found the man pages won't be generated or installed. Move Asciidoctor to the list of package build dependencies in various places. This commit includes the conversion script (pod2adoc.py), which will be removed later. Line count sanity check: Man page .pod .adoc androiddump 260 280 asn2deb 93 105 capinfos 401 471 captype 54 55 ciscodump 241 269 dftest 42 42 dpauxmon 153 169 dumpcap 464 534 editcap 528 583 etwdump 136 156 extcap 157 181 idl2deb 91 103 idl2wrs 120 100 mergecap 206 207 mmdbresolve 75 75 randpkt 107 111 randpktdump 158 184 rawshark 558 610 reordercap 76 78 sdjournal 145 157 sshdump 272 302 text2pcap 274 312 tshark 2135 2360 udpdump 133 151 wireshark-filter 486 479 wireshark 2967 3420
2021-06-18 03:20:51 -07:00
== Requirements
Svn stuff: - Add eol-style native to all text files - Add Id attributes Add $Id: $ to all text files Makefile: - add several files and directories to make clean - Add comments for values on Suse 9.1 catalog.xml: - Add comments for values on Suse 9.1 svn path=/trunk/; revision=11618
2004-08-06 21:06:27 +00:00
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>
2020-04-14 11:49:04 -07: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.
WSUG: Convert the "Capturing" chapter to AsciiDoc. Leave most of the content intact for now. Add a section on markup conventions to README.txt. Remove the .mediaobject border. Change-Id: I06cfd482a4c8ea63c90b9f59fcdf2afaf636a4a2 Reviewed-on: https://code.wireshark.org/review/3821 Reviewed-by: Gerald Combs <gerald@wireshark.org>
2014-08-18 09:31:26 -07:00
Docs+Packaging: Convert our man pages to Asciidoctor. Convert doc/*.pod to Asciidoctor. This: * Means we use the same markup for our man pages, the guides, and release notes. * Lets us add versions to our man pages. * Gives us more formatting options, e.g. AsciiDoc supports `commands`, nested lists and makes it easy to include version information. The manpage backend doesn't seem to support tables very well, unfortunately. Convert our CMake configuration to produce *roff and html man pages using Asciidoctor. Add a "manarg" block macro which makes our synopses wrap correctly. Similar to the release notes, guides, and FAQ, if Asciidoctor isn't found the man pages won't be generated or installed. Move Asciidoctor to the list of package build dependencies in various places. This commit includes the conversion script (pod2adoc.py), which will be removed later. Line count sanity check: Man page .pod .adoc androiddump 260 280 asn2deb 93 105 capinfos 401 471 captype 54 55 ciscodump 241 269 dftest 42 42 dpauxmon 153 169 dumpcap 464 534 editcap 528 583 etwdump 136 156 extcap 157 181 idl2deb 91 103 idl2wrs 120 100 mergecap 206 207 mmdbresolve 75 75 randpkt 107 111 randpktdump 158 184 rawshark 558 610 reordercap 76 78 sdjournal 145 157 sshdump 272 302 text2pcap 274 312 tshark 2135 2360 udpdump 133 151 wireshark-filter 486 479 wireshark 2967 3420
2021-06-18 03:20:51 -07:00
== Asciidoctor Markup
WSUG: Convert the "Capturing" chapter to AsciiDoc. Leave most of the content intact for now. Add a section on markup conventions to README.txt. Remove the .mediaobject border. Change-Id: I06cfd482a4c8ea63c90b9f59fcdf2afaf636a4a2 Reviewed-on: https://code.wireshark.org/review/3821 Reviewed-by: Gerald Combs <gerald@wireshark.org>
2014-08-18 09:31:26 -07: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 15:03:55 -07:00
The User’s and Developer’s Guides were originally written in DocBook and
Documentation: convert http URLS to https Remove some dead links or point them to archive.org while at it. All updated links have been verified. Change-Id: Icf02167a13d5fe9dfce39ea57525b3f185554c9d Reviewed-on: https://code.wireshark.org/review/34028 Petri-Dish: Peter Wu <peter@lekensteyn.nl> Tested-by: Petri Dish Buildbot Reviewed-by: Anders Broman <a.broman58@gmail.com>
2019-07-20 16:13:59 +01: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 15:03:55 -07:00
switched from AsciiDoc to Asciidoctor. As a result we currently use
Documentation: convert http URLS to https Remove some dead links or point them to archive.org while at it. All updated links have been verified. Change-Id: Icf02167a13d5fe9dfce39ea57525b3f185554c9d Reviewed-on: https://code.wireshark.org/review/34028 Petri-Dish: Peter Wu <peter@lekensteyn.nl> Tested-by: Petri Dish Buildbot Reviewed-by: Anders Broman <a.broman58@gmail.com>
2019-07-20 16:13:59 +01: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 15:03:55 -07:00
to Asciidoctor’s modern markup at a later date.
WSUG: Convert the "Capturing" chapter to AsciiDoc. Leave most of the content intact for now. Add a section on markup conventions to README.txt. Remove the .mediaobject border. Change-Id: I06cfd482a4c8ea63c90b9f59fcdf2afaf636a4a2 Reviewed-on: https://code.wireshark.org/review/3821 Reviewed-by: Gerald Combs <gerald@wireshark.org>
2014-08-18 09:31:26 -07: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 15:03:55 -07:00
Please use the following conventions when writing documentation:
WSUG: Convert the "Capturing" chapter to AsciiDoc. Leave most of the content intact for now. Add a section on markup conventions to README.txt. Remove the .mediaobject border. Change-Id: I06cfd482a4c8ea63c90b9f59fcdf2afaf636a4a2 Reviewed-on: https://code.wireshark.org/review/3821 Reviewed-by: Gerald Combs <gerald@wireshark.org>
2014-08-18 09:31:26 -07: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 15:03:55 -07:00
- Window and dialog box names should be in “curly quotes”.
WSUG: Convert the "Capturing" chapter to AsciiDoc. Leave most of the content intact for now. Add a section on markup conventions to README.txt. Remove the .mediaobject border. Change-Id: I06cfd482a4c8ea63c90b9f59fcdf2afaf636a4a2 Reviewed-on: https://code.wireshark.org/review/3821 Reviewed-by: Gerald Combs <gerald@wireshark.org>
2014-08-18 09:31:26 -07: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 15:03:55 -07:00
- Use Asciidoctor macros for buttons, keys, and menus. Note that these
are currently experimental:
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>
2020-04-14 11:49:04 -07:00
** The btn:[Start] button
Docs: Add a live preview section to the docbook README. Change-Id: I92462073a65f1673a9b5e036ec72ade90558eb1c Reviewed-on: https://code.wireshark.org/review/27935 Reviewed-by: Gerald Combs <gerald@wireshark.org>
2018-05-31 11:14:27 -07: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 15:03:55 -07:00
This ensures that UI elements are shown consistently and lets us apply styles
to each type of element.
WSUG: Convert the "Capturing" chapter to AsciiDoc. Leave most of the content intact for now. Add a section on markup conventions to README.txt. Remove the .mediaobject border. Change-Id: I06cfd482a4c8ea63c90b9f59fcdf2afaf636a4a2 Reviewed-on: https://code.wireshark.org/review/3821 Reviewed-by: Gerald Combs <gerald@wireshark.org>
2014-08-18 09:31:26 -07: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 15:03:55 -07:00
- Command line examples should reflect the OS:
+
WSUG: Convert the "Capturing" chapter to AsciiDoc. Leave most of the content intact for now. Add a section on markup conventions to README.txt. Remove the .mediaobject border. Change-Id: I06cfd482a4c8ea63c90b9f59fcdf2afaf636a4a2 Reviewed-on: https://code.wireshark.org/review/3821 Reviewed-by: Gerald Combs <gerald@wireshark.org>
2014-08-18 09:31:26 -07:00
----
$ echo Linux and UNIX
----
Docs: Add a live preview section to the docbook README. Change-Id: I92462073a65f1673a9b5e036ec72ade90558eb1c Reviewed-on: https://code.wireshark.org/review/27935 Reviewed-by: Gerald Combs <gerald@wireshark.org>
2018-05-31 11:14:27 -07:00
+
WSUG: Convert the "Capturing" chapter to AsciiDoc. Leave most of the content intact for now. Add a section on markup conventions to README.txt. Remove the .mediaobject border. Change-Id: I06cfd482a4c8ea63c90b9f59fcdf2afaf636a4a2 Reviewed-on: https://code.wireshark.org/review/3821 Reviewed-by: Gerald Combs <gerald@wireshark.org>
2014-08-18 09:31:26 -07:00
----
C:\> echo Windows
----
WSDG/WSUG: add missing asciidoc admonition icons Closes #17474
2022-02-07 22:58:52 -06:00
Admonitions ([NOTE], [TIP], [IMPORTANT], [CAUTION] and [WARNING]) can be used to highlight important
WSUG: Convert the "Capturing" chapter to AsciiDoc. Leave most of the content intact for now. Add a section on markup conventions to README.txt. Remove the .mediaobject border. Change-Id: I06cfd482a4c8ea63c90b9f59fcdf2afaf636a4a2 Reviewed-on: https://code.wireshark.org/review/3821 Reviewed-by: Gerald Combs <gerald@wireshark.org>
2014-08-18 09:31:26 -07:00
information. Keep in mind that they interrupt the flow of text by design. Too
many (especially in a row) are distracting and annoying.
Docs+Packaging: Convert our man pages to Asciidoctor. Convert doc/*.pod to Asciidoctor. This: * Means we use the same markup for our man pages, the guides, and release notes. * Lets us add versions to our man pages. * Gives us more formatting options, e.g. AsciiDoc supports `commands`, nested lists and makes it easy to include version information. The manpage backend doesn't seem to support tables very well, unfortunately. Convert our CMake configuration to produce *roff and html man pages using Asciidoctor. Add a "manarg" block macro which makes our synopses wrap correctly. Similar to the release notes, guides, and FAQ, if Asciidoctor isn't found the man pages won't be generated or installed. Move Asciidoctor to the list of package build dependencies in various places. This commit includes the conversion script (pod2adoc.py), which will be removed later. Line count sanity check: Man page .pod .adoc androiddump 260 280 asn2deb 93 105 capinfos 401 471 captype 54 55 ciscodump 241 269 dftest 42 42 dpauxmon 153 169 dumpcap 464 534 editcap 528 583 etwdump 136 156 extcap 157 181 idl2deb 91 103 idl2wrs 120 100 mergecap 206 207 mmdbresolve 75 75 randpkt 107 111 randpktdump 158 184 rawshark 558 610 reordercap 76 78 sdjournal 145 157 sshdump 272 302 text2pcap 274 312 tshark 2135 2360 udpdump 133 151 wireshark-filter 486 479 wireshark 2967 3420
2021-06-18 03:20:51 -07:00
== Custom Asciidoctor Macros
Docs: Move our AsciiDoctor macros to the doc directory
2024-07-10 09:26:01 -07:00
The following custom macros are available in `doc/asciidoctor-macros`:
Docs+Packaging: Convert our man pages to Asciidoctor. Convert doc/*.pod to Asciidoctor. This: * Means we use the same markup for our man pages, the guides, and release notes. * Lets us add versions to our man pages. * Gives us more formatting options, e.g. AsciiDoc supports `commands`, nested lists and makes it easy to include version information. The manpage backend doesn't seem to support tables very well, unfortunately. Convert our CMake configuration to produce *roff and html man pages using Asciidoctor. Add a "manarg" block macro which makes our synopses wrap correctly. Similar to the release notes, guides, and FAQ, if Asciidoctor isn't found the man pages won't be generated or installed. Move Asciidoctor to the list of package build dependencies in various places. This commit includes the conversion script (pod2adoc.py), which will be removed later. Line count sanity check: Man page .pod .adoc androiddump 260 280 asn2deb 93 105 capinfos 401 471 captype 54 55 ciscodump 241 269 dftest 42 42 dpauxmon 153 169 dumpcap 464 534 editcap 528 583 etwdump 136 156 extcap 157 181 idl2deb 91 103 idl2wrs 120 100 mergecap 206 207 mmdbresolve 75 75 randpkt 107 111 randpktdump 158 184 rawshark 558 610 reordercap 76 78 sdjournal 145 157 sshdump 272 302 text2pcap 274 312 tshark 2135 2360 udpdump 133 151 wireshark-filter 486 479 wireshark 2967 3420
2021-06-18 03:20:51 -07:00
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.
Docs: Add a live preview section to the docbook README. Change-Id: I92462073a65f1673a9b5e036ec72ade90558eb1c Reviewed-on: https://code.wireshark.org/review/27935 Reviewed-by: Gerald Combs <gerald@wireshark.org>
2018-05-31 11:14:27 -07: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
Rename our .asciidoc files to .adoc As noted in "AsciiDoc Recommended Practices" at https://asciidoctor.org/docs/asciidoc-recommended-practices/, the AsciiDoc/Asciidoctor community seems to have settled on ".adoc" as a file extension and that's the one preferred by the Asciidoctor project. Update our filenames to match. Change-Id: I2d352623d42d65d950b64310c3655b0fd177ee8c Reviewed-on: https://code.wireshark.org/review/32037 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>
2019-02-14 15:23:05 -08: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,
Docs: Add a live preview section to the docbook README. Change-Id: I92462073a65f1673a9b5e036ec72ade90558eb1c Reviewed-on: https://code.wireshark.org/review/27935 Reviewed-by: Gerald Combs <gerald@wireshark.org>
2018-05-31 11:14:27 -07: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.
Reference in New Issue Copy Permalink