doc/README.documentation.adoc

   1
   2 :experimental:
   3 = Introduction
   4
   5 This directory contains the source files needed to build the:
   6
   7 - Wireshark User’s Guide
   8 - Wireshark Developer’s Guide
   9 - Release notes
  10 - Lua Reference
  11
  12 To build everything, build the `all_guides` target, e.g. `ninja
  13 all_guides` or `msbuild all_guides.vcxproj`. Requirements are listed
  14 below.
  15
  16 The guides and release notes are written in
  17 https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor syntax].
  18 For more information see https://asciidoctor.org.
  19
  20 == Requirements
  21
  22 Ultimately we'd like to reduce the toolchain requirements to AsciidoctorJ alone, but that's not yet possible.
  23 Additional tooling is required for the HTML and HTMLHelp targets.
  24 See the https://www.wireshark.org/docs/wsdg_html_chunked/ChToolsDocumentationToolchain.html[Developer's Guide] for instructions on installing required packages for your platform.
  25
  26 == Asciidoctor Markup
  27
  28 The User’s and Developer’s Guides were originally written in DocBook and
  29 were later converted to https://asciidoc.org/[AsciiDoc]. We subsequently
  30 switched from AsciiDoc to Asciidoctor.
  31 We currently use Asciidoctor’s modern (>= 1.5.0) syntax.
  32
  33 Please use the following conventions when writing documentation:
  34
  35 - Window and dialog box names should be in “curly quotes”.
  36
  37 - Use Asciidoctor macros for buttons, keys, and menus. Note that these
  38   are currently experimental:
  39
  40 ** The btn:[Start] button
  41 ** Press kbd:[Shift+Ctrl+P] to open the preferences dialog.
  42 ** Select menu:File[Open] from the main menu.
  43
  44 This ensures that UI elements are shown consistently and lets us apply styles
  45 to each type of element.
  46
  47 - Command line examples should reflect the OS:
  48 +
  49 ----
  50 $ echo Linux and UNIX
  51 ----
  52 +
  53 ----
  54 C:\> echo Windows
  55 ----
  56
  57 Admonitions ([NOTE], [TIP], [IMPORTANT], [CAUTION] and [WARNING]) can be used to highlight important
  58 information. Keep in mind that they interrupt the flow of text by design. Too
  59 many (especially in a row) are distracting and annoying.
  60
  61 == Custom Asciidoctor Macros
  62
  63 The following custom macros are available in `doc/asciidoctor-macros`:
  64
  65 commaize-block::
  66 Sorts a list of items and separates them with commas with an "and" preceding the last item.
  67
  68 cveidlink-inline-macro::
  69 Links a CVE ID to cve.mitre.org.
  70
  71 manarg-block::
  72 Ensures that individual arguments don't wrap in order to improve readability.
  73
  74 wsbuglink-inline-macro::
  75 Links an issue number to gitlab.org/wireshark/wireshark/-/issues.
  76
  77 wssalink-inline-macro::
  78 Links a security advisory to www.wireshark.org.
  79
  80 == Asciidoctor Live Preview
  81
  82 The Asciidoctor project provides a JavaScript version of Asciidoctor
  83 (asciidoctor.js), which enables live previews in many web browsers and
  84 text editors. See the
  85 https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/[Live
  86 Preview] documentation for more information.
  87
  88 Note that our documentation depends on attributes defined in
  89 _attributes.adoc_. The User’s Guide and Developer’s Guide are split
  90 across several files, and only the top-level _user-guide.adoc_ and
  91 _developer-guide.adoc_ include _attributes.adoc_. As a result,
  92 some markup will be incomplete. You can work around this somewhat by
  93 adding the `experimental` attribute to your Live Preview settings.