osmocom
/
wireshark
11
0
Fork 1
Code Issues Pull Requests Projects Releases Wiki Activity

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>
This commit is contained in:
Gerald Combs 2018-05-31 11:14:27 -07:00
parent 241eeb6333
commit f6679c75f7
1 changed files with 20 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
docbook/README.adoc
View File

@ -79,29 +79,43 @@ Please use the following conventions when writing documentation:
- Use Asciidoctor macros for buttons, keys, and menus. Note that these - Use Asciidoctor macros for buttons, keys, and menus. Note that these
are currently experimental: are currently experimental:
-- The button:[Start] button ** The button:[Start] button
-- Press kbd:[Shift+Ctrl+P] to open the preferences dialog. ** Press kbd:[Shift+Ctrl+P] to open the preferences dialog.
-- Select menu:File[Open] from the main menu. ** Select menu:File[Open] from the main menu.
This ensures that UI elements are shown consistently and lets us apply styles This ensures that UI elements are shown consistently and lets us apply styles
to each type of element. to each type of element.
- Command line examples should reflect the OS: - Command line examples should reflect the OS:
+ +
+++
---- ----
$ echo Linux and UNIX $ echo Linux and UNIX
---- ----
+
---- ----
C:\> echo Windows C:\> echo Windows
---- ----
+++
Admonitions ([NOTE], [TIP], and [WARNING]) can be used to highlight important 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 information. Keep in mind that they interrupt the flow of text by design. Too
many (especially in a row) are distracting and annoying. many (especially in a row) are distracting and annoying.
== 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
_attributes.asciidoc_. The User’s Guide and Developer’s Guide are split
across several files, and only the top-level _user-guide.asciidoc_ and
_developer-guide.asciidoc_ include _attributes.asciidoc_. As a result,
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.
= HTML Help Alternatives = HTML Help Alternatives
Ideally we would ship documentation with Wireshark that is pleasant to Ideally we would ship documentation with Wireshark that is pleasant to