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

98 lines
3.4 KiB
Plaintext
Raw Permalink 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
NSIS+WiX: Switch from "NEWS" to "Release Notes.html" A file called "Release Notes" is a more obvious place for our release notes than "NEWS", so use that name. Our release notes contain lots of URLs, so make it an HTML file. Remove the "NEWS" file and related targets.
2024-07-26 10:32:05 -07:00
- Release notes
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
- 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
Fix building docs on Windows 1. Update documentation to point to doc\all_guides.vcxproj 2. Add fonts that asciidoctor-pdf build required to not fail. 3. Fix build errors with removal of some bracketed text Fixes #20528
2025-05-14 15:20:10 -04:00
all_guides` or `msbuild doc\all_guides.vcxproj`. Requirements are listed
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
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
docs: Update README.documentation.adoc
2025-03-03 11:34:30 -08:00
All of the documentation in this directory is 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
See the https://www.wireshark.org/docs/wsdg_html_chunked/ChToolsDocumentationToolchain.html[Developer's Guide] for instructions on installing required packages for your platform.
docs: Update README.documentation.adoc
2025-03-03 11:34:30 -08:00
Ultimately we'd like to reduce the toolchain requirements to Asciidoctor alone, but that's not yet possible.
Additional tooling is required for the HTML targets.
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: Update README.documentation.adoc
2025-03-03 11:34:30 -08:00
== Markup and Typographic Conventions
In order to keep the markup for filenames, commands, and other content consistent, please follow the guidelines in __common_src/typographic_conventions.adoc__.
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: Asciidoctor compat-mode transitioned to modern syntax
2024-07-27 17:18:34 +00:00
We currently use Asciidoctor’s modern (>= 1.5.0) syntax.
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
docs: Update README.documentation.adoc
2025-03-03 11:34:30 -08:00
- Use Asciidoctor macros for buttons, keys, and menus.
Note that these require the `:experimental:` attribute:
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
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
Docs: update README files
2024-07-28 14:47:09 -05:00
adding the `experimental` attribute to your Live Preview settings.
docs: Update README.documentation.adoc
2025-03-03 11:34:30 -08:00
== Historical Notes
The User’s and Developer’s Guides were originally written in DocBook and were later converted to https://asciidoc.org/[AsciiDoc].
The AsciiDoc markup has been modernized over time and we migrated our documentation toolchain to Asciidoctor.
Reference in New Issue Copy Permalink