diff options
| author | Gerald Combs <gerald@zing.org> | 2014-08-18 09:31:26 -0700 |
|---|---|---|
| committer | Gerald Combs <gerald@wireshark.org> | 2014-08-25 22:15:17 +0000 |
| commit | a84937198ba1c0ea5313aebd6d9cecc23f298af3 (patch) | |
| tree | ce0f26665d13151b8a3e2aed0b88fc5b5523107b /docbook/README.txt | |
| parent | d3728738ddbb24daf248aa4d2f9ad94702a1ed0f (diff) | |
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>
Diffstat (limited to 'docbook/README.txt')
| -rw-r--r-- | docbook/README.txt | 40 |
1 files changed, 34 insertions, 6 deletions
diff --git a/docbook/README.txt b/docbook/README.txt index 2404e72866..7b56f62dd1 100644 --- a/docbook/README.txt +++ b/docbook/README.txt @@ -94,11 +94,40 @@ rename it to jimi-1.0.jar. AsciiDoc -------- -Text documentation format and conversion suite: -http://asciidoc.org/. AsciiDoc can use either w3m (default) or Lynx -for plain text output. We use AsciiDoc for the Developer's Guide and -for the release notes; Lynx as well is used for the official plaintext -release announcments. +Text documentation format and conversion suite: http://asciidoc.org/. AsciiDoc +can use either w3m (default) or Lynx for plain text output. We use AsciiDoc for +the Developer's Guide, User's Guide, and for the release notes. Lynx is used to +render the official plaintext release announcments. + +The AsciiDoc files have been converted from DocBook. In a lot of cases the +markup is wrong, inconsistent, or both. Use the following markup conventions +for any new or revised text: + +- Window and dialog box names should be in ``curly quotes''. + +- Use Asciidoctor compatibility macros for buttons, keys, and menus: + + The button:[Start] button + Press kbd:[Shift+Ctrl+P] to open the preferences dialog. + Select menu:File[Open] from the main menu. + + This ensures that UI elemnents are shown consistently and lets us apply styles + to each type of element. + +- Command line examples should reflect the OS: + +---- +$ echo Linux and UNIX +---- + +---- +C:\> echo Windows +---- + +Admonitions ([NOTE], [TIP], and [WARNING]) can be used to highlight important +information. Keep in mind that they interrupt the flow of text by design. Too +many (especially in a row) are distracting and annoying. + Lynx ---- @@ -305,4 +334,3 @@ http://www.codeproject.com/KB/winhelp/docbook_howto.aspx FO Parameter Reference by Norman Walsh http://docbook.sourceforge.net/release/xsl/current/doc/fo/ - |