WSUG+WSDG: Add a typographic conventions section.

Create a common_src directory for common guide content. Add a
typographic convention section. Update some of the content accordingly.

Change-Id: I4f69c0f52a985c48e07fa0628b19734ec691f74e
Reviewed-on: https://code.wireshark.org/review/23131
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot <buildbot-no-reply@wireshark.org>
Reviewed-by: Anders Broman <a.broman58@gmail.com>

11 files changed, 154 insertions, 93 deletions

diff --git a/docbook/CMakeLists.txt b/docbook/CMakeLists.txt
index 121f943e40..2f32590df3 100644
--- a/docbook/CMakeLists.txt
+++ b/docbook/CMakeLists.txt
@@ -57,6 +57,10 @@ else()
 	endmacro()
 endif()
 
+set(COMMON_FILES
+	common_src/GPL_appendix.asciidoc
+)
+
 set(COMMON_GRAPHICS
 	common_graphics/note.svg
 	common_graphics/tip.svg
@@ -81,6 +85,7 @@ set(WSUG_FILES
 	wsug_src/WSUG_chapter_use.asciidoc
 	wsug_src/WSUG_chapter_work.asciidoc
 	wsug_src/WSUG_preface.asciidoc
+	${COMMON_FILES}
 )
 
 set(WSUG_GRAPHICS
@@ -230,6 +235,7 @@ set(WSDG_FILES
 	wsdg_src/WSDG_chapter_works.asciidoc
 	wsdg_src/WSDG_preface.asciidoc
 	wsluarm.asciidoc
+	${COMMON_FILES}
 )
 
 set(WSDG_GRAPHICS
@@ -331,7 +337,7 @@ if(ENABLE_HTML_GUIDES OR ENABLE_PDF_GUIDES OR ENABLE_CHM_GUIDES)
 	add_custom_target(user_guide_docbook DEPENDS generate_user-guide.xml)
 	set_target_properties(user_guide_docbook PROPERTIES FOLDER "Docbook")
 
-	ASCIIDOC2DOCBOOK(developer-guide.asciidoc ASCIIDOC_WSLUARM_CONF_FILES WSDG_SOURCE WSDG_BUILT_DEPS)
+	ASCIIDOC2DOCBOOK(developer-guide.asciidoc ASCIIDOC_CONF_FILES WSDG_SOURCE WSDG_BUILT_DEPS)
 	add_custom_target(developer_guide_docbook DEPENDS generate_developer-guide.xml)
 	set_target_properties(developer_guide_docbook PROPERTIES FOLDER "Docbook")
 
diff --git a/docbook/Makefile.am b/docbook/Makefile.am
index f0faba8e89..3434ff996b 100644
--- a/docbook/Makefile.am
+++ b/docbook/Makefile.am
@@ -213,6 +213,10 @@ WSDG_GRAPHICS =	\
 	wsdg_graphics/ws-logo.png		\
 	wsdg_graphics/toolbar/dummy.dummy
 
+COMMON_FILES = \
+	common_src/GPL_appendix.asciidoc	\
+	common_src/typographic_conventions.asciidoc
+
 COMMON_GRAPHICS = \
 	common_graphics/note.svg	\
 	common_graphics/tip.svg		\
@@ -222,11 +226,11 @@ COMMON_GRAPHICS = \
 WSUG_DIST =	\
 	user-guide.asciidoc	\
 	attributes.asciidoc	\
-	GPL_appendix.asciidoc	\
 	custom_layer_chm.xsl	\
 	custom_layer_pdf.xsl	\
 	$(WSUG_FILES)		\
 	$(WSUG_GRAPHICS)	\
+	$(COMMON_FILES)		\
 	$(COMMON_GRAPHICS)
 
 WSUG_SOURCE = $(WSUG_GENERATED_SOURCE) $(WSUG_DIST)
@@ -235,11 +239,11 @@ WSUG_SOURCE = $(WSUG_GENERATED_SOURCE) $(WSUG_DIST)
 WSDG_DIST =	\
 	developer-guide.asciidoc	\
 	attributes.asciidoc	\
-	GPL_appendix.asciidoc	\
 	custom_layer_chm.xsl	\
 	custom_layer_pdf.xsl	\
 	$(WSDG_FILES)		\
 	$(WSDG_GRAPHICS)	\
+	$(COMMON_FILES)		\
 	$(COMMON_GRAPHICS)
 
 WSDG_SOURCE = $(WSDG_GENERATED_SOURCE) $(WSDG_DIST)
diff --git a/docbook/GPL_appendix.asciidoc b/docbook/common_src/GPL_appendix.asciidoc
index 61ab50e7aa..61ab50e7aa 100644
--- a/docbook/GPL_appendix.asciidoc
+++ b/docbook/common_src/GPL_appendix.asciidoc
diff --git a/docbook/common_src/typographic_conventions.asciidoc b/docbook/common_src/typographic_conventions.asciidoc
new file mode 100644
index 0000000000..3091ebcf15
--- /dev/null
+++ b/docbook/common_src/typographic_conventions.asciidoc
@@ -0,0 +1,80 @@
+[[PrefaceTypographicConventions]]
+
+=== Typographic Conventions
+
+The following table shows the typographic conventions that are used in this guide.
+
+// https://github.com/oreillymedia/orm_book_samples/blob/master/asciidoc_only/preface.asciidoc
+
+.Typographic Conventions
+[options="header",cols="1,3,3"]
+|===============
+|Style|Description|Example
+|'Italic'             |File names, folder names, and extensions |'C:\Development\wireshark'.
+|`Monospace`          |Commands, flags, and environment variables|CMake's `-G` option.
+|**`Bold Monospace`** |Commands that should be run by the user|Run **`cmake -G Ninja ..`**.
+|button:[Button]      |Dialog and window buttons |Press button:[Launch] to go to the Moon.
+|kbd:[Key]            |Keyboard shortcut |Press kbd:[Ctrl+Down] to move to the next packet.
+|menu:Menu[]          |Menu item |Select menu:Go[Next Packet to move to the next packet.
+|===============
+
+==== Admonitions
+
+Important and notable items are marked as follows:
+
+[WARNING]
+.This is a warning
+====
+You should pay attention to a warning, otherwise data loss might occur.
+====
+
+[NOTE]
+.This is a note
+====
+A note will point you to common mistakes and things that might not be obvious.
+====
+
+[TIP]
+.This is a tip
+====
+Tips are helpful for your everyday work using Wireshark.
+====
+
+==== Shell Prompt and Source Code Examples
+
+.Bourne shell, normal user
+----
+$ # This is a comment
+$ git config --global log.abbrevcommit true
+----
+
+.Bourne shell, root user
+----
+# # This is a comment
+# ninja install
+----
+
+.Command Prompt (cmd.exe)
+----
+>rem This is a comment
+>cd C:\Development
+----
+
+.PowerShell
+----
+PS$># This is a comment
+PS$>choco list -l
+----
+
+.C Source Code
+----
+#include "config.h"
+
+/* This method dissects foos */
+static int
+dissect_foo_message(tvbuff_t *tvb, packet_info *pinfo _U_, proto_tree *tree _U_, void *data _U_)
+{
+    /* TODO: implement your dissecting code */
+    return tvb_captured_length(tvb);
+}
+----
diff --git a/docbook/developer-guide.asciidoc b/docbook/developer-guide.asciidoc
index d70a9219d7..70167cefe2 100644
--- a/docbook/developer-guide.asciidoc
+++ b/docbook/developer-guide.asciidoc
@@ -5,10 +5,12 @@ include::attributes.asciidoc[]
 
 [[Preface]]
 ["preface",id="Preface"]
-= Preface
+== Preface
 
 include::wsdg_src/WSDG_preface.asciidoc[]
 
+include::common_src/typographic_conventions.asciidoc[]
+
 [[PartEnvironment]]
 = Wireshark Build Environment
 [partintro]
diff --git a/docbook/user-guide.asciidoc b/docbook/user-guide.asciidoc
index e034a37120..0bc92acab6 100644
--- a/docbook/user-guide.asciidoc
+++ b/docbook/user-guide.asciidoc
@@ -9,6 +9,8 @@ include::attributes.asciidoc[]
 
 include::wsug_src/WSUG_preface.asciidoc[]
 
+include::common_src/typographic_conventions.asciidoc[]
+
 // Chapters
 include::wsug_src/WSUG_chapter_introduction.asciidoc[]
 include::wsug_src/WSUG_chapter_build_install.asciidoc[]
diff --git a/docbook/ws.css b/docbook/ws.css
index f7c58fe1af..766076df0f 100644
--- a/docbook/ws.css
+++ b/docbook/ws.css
@@ -127,6 +127,14 @@ tt.literal, code.literal {
   font-weight: bold;
 }
 
+.guibutton {
+  background: #f4f4f4;
+  border: 0.5px solid #f4f4f4;
+  border-radius: 0.25em;
+  padding-left: 0.25em;
+  padding-right: 0.25em;
+}
+
 .keycap, .guimenu, .guisubmenu, .guimenuitem {
   border: 0.5px solid silver;
   padding-left: 0.25em;
diff --git a/docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc b/docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc
index c012d6cba0..fcfb13132b 100644
--- a/docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc
+++ b/docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc
@@ -112,12 +112,12 @@ example, the ``msvc2015 64-bit'' component is used to build the official
 components as they aren't required.
 
 Note that installation of separate Qt components are required for 32 bit
-and 64 bit builds, e.g. `msvc2015 32-bit` and `msvc2015 64-bit`. The
+and 64 bit builds, e.g. ``msvc2015 32-bit'' and ``msvc2015 64-bit''. The
 environment variable `QT5_BASE_DIR` should be set as appropriate for your
 environment and should point to the Qt directory that contains the bin
-directory, e.g. `C:\Qt\5.9.1\msvc2015_64`
+directory, e.g. 'C:\Qt\5.9.1\msvc2015_64'
 
-The Qt maintenance tool (`C:\Qt\MaintenanceTool.exe`) can be used to
+The Qt maintenance tool ('C:\Qt\MaintenanceTool.exe') can be used to
 upgrade Qt to newer versions.
 
 [[ChSetupCygwin]]
@@ -160,7 +160,7 @@ You might also have to install
 if installing Devel/bison doesn't provide a working version of Bison. If
 m4 is missing bison will fail.
 
-After clicking the Next button several times, the setup
+After clicking the button:Next[] button several times, the setup
 will then download and install the selected packages (this
 may take a while).
 
@@ -169,12 +169,12 @@ Alternatively you can install Cygwin and its packages using Chocolatey:
 ----
 PS$>choco install cygwin
 PS$>choco install cyg-get
-//PS$>choco install sed asciidoc [...] -source cygwin
 ----
+//PS$>choco install sed asciidoc [...] -source cygwin
 
 Chocolatey installs Cygwin in 'C:\tools\cygwin' by default.
 
-You can directly download packages via cyg-get
+You can directly download packages via `cyg-get`
 
 ----
 PS$>cyg-get asciidoc patch docbook-xml45 [...]
@@ -194,7 +194,7 @@ PS$>choco install winflexbison
 Get the Python 3.5 or 2.7 installer from http://python.org/download/[] and
 install Python into the default location ('C:\Python35' or 'C:\Python27').
 
-Why is this recommended? Cygwin's `/usr/bin/python` is a Cygwin-specific
+Why is this recommended? Cygwin's '/usr/bin/python' is a Cygwin-specific
 symbolic link which cannot be run from Windows. The native package is faster
 as well.
 
@@ -309,11 +309,11 @@ Using Git extensions:
 
 . In the main screen select _Clone repository_. Fill in the following:
 +
-Repository to clone: `https://code.wireshark.org/review/wireshark`
+Repository to clone: *`https://code.wireshark.org/review/wireshark`*
 +
-Destination: Your top-level development directory, e.g. `C:\Development`.
+Destination: Your top-level development directory, e.g. 'C:\Development'.
 +
-Subdirectory to create: Anything you'd like. Usually `wireshark`.
+Subdirectory to create: Anything you'd like. Usually 'wireshark'.
 +
 [TIP]
 .Check your paths
@@ -321,8 +321,8 @@ Subdirectory to create: Anything you'd like. Usually `wireshark`.
 Make sure your repository path doesn't contain spaces.
 ====
 
-. Click the _Clone_ button. Git Extensions should start cloning the
-   Wireshark repository.
+. Click the button:Clone[] button. Git Extensions should start cloning the
+  Wireshark repository.
 
 [[ChSetupPrepareCommandCom]]
 
@@ -446,7 +446,7 @@ At the end of the CMake generation process the following should be displayed:
 
 If you get any other output, there is an issue in your envirnment that must be rectified before building.
 Check the parameters passed to CMake, especially the `-G` option and the path to the Wireshark sources and
-the environment variables WIRESHARK_BASE_DIR and QT5_BASE_DIR.
+the environment variables `WIRESHARK_BASE_DIR` and `QT5_BASE_DIR`.
 
 [[ChWin32Build]]
 
@@ -467,16 +467,16 @@ to build Wireshark.
 
 . Wait for Wireshark to compile. This will take a while, and there will be a lot of text output in the command prompt window
 
-. For the Qt version run `C:\Development\wsbuild32\run\RelWithDebInfo\Wireshark.exe` and make sure it starts.
+. Run *`C:\Development\wsbuild32\run\RelWithDebInfo\Wireshark.exe`* and make sure it starts.
 
-. Open 'Help -> About'. If it shows your "private" program
+. Open menu:Help[About]. If it shows your "private" program
 version, e.g.: Version {wireshark-version}-myprotocol123
 congratulations! You have compiled your own version of Wireshark!
 
-You may also open the Wireshark solution file (Wireshark.sln) in the Visual Studio IDE and build there.
+You may also open the Wireshark solution file ('Wireshark.sln') in the Visual Studio IDE and build there.
 
 TIP: If compilation fails for suspicious reasons after you changed some source
-files try to clean the build files by running msbuild /m /p:Configuration=RelWithDebInfo Wireshark.sln /t:Clean
+files try to clean the build files by running *`msbuild /m /p:Configuration=RelWithDebInfo Wireshark.sln /t:Clean`*
 and then building the solution again.
 
 The build files produced by CMake will regenerate themselves if required by changes in the source tree.
@@ -507,13 +507,13 @@ Note that the 32-bit version of NSIS will work for both 32-bit and
 64-bit versions of Wireshark. NSIS v3 is recommended and may be required
 in the future.
 
-Note: If you do not yet have a copy of vcredist_x86.exe or vcredist_x64.exe in ./wireshark-winXX-libs (where XX is 32 or 64) you will need to download the appropriate file and place it in ./wireshark-winXX-libs before starting this step.
+Note: If you do not yet have a copy of vcredist_x86.exe or vcredist_x64.exe in './wireshark-win**XX**-libs' (where *'XX'* is 32 or 64) you will need to download the appropriate file and place it in './wireshark-win**XX**-libs' before starting this step.
 
-If building an x86 version using a Visual Studio "Express" edition or an x64 version with any edition, then you must have the appropriate vcredist file for your compiler in the support libraries directory (vcredist_x86.exe in wireshark-32-libs or vcredist_x64.exe in wireshark-win64-libs).
+If building an x86 version using a Visual Studio "Express" edition or an x64 version with any edition, then you must have the appropriate vcredist file for your compiler in the support libraries directory ('vcredist_x86.exe' in 'wireshark-32-libs' or 'vcredist_x64.exe' in 'wireshark-win64-libs').
 
 The files can be located in the Visual Studio install directory for non-Express edition builds, or downloaded from Microsoft for Expresss edition builds.
 
-Note you must use the correct version of vcredist for your compiler, unfortunately they all have the same name (vcredist_x86.exe or vcredist_x64.exe).  You can use Windows Explorer and examine the Properties >> Details tab for a vcredist file to determine which compiler version the file is for use with.
+Note you must use the correct version of vcredist for your compiler, unfortunately they all have the same name ('vcredist_x86.exe' or 'vcredist_x64.exe').  You can use Windows Explorer and examine the `Properties -> Details' tab for a vcredist file to determine which compiler version the file is for use with.
 
 . If you've closed the Visual Studio Command Prompt <<ChSetupPrepareCommandCom,prepare>> it again.
 
diff --git a/docbook/wsdg_src/WSDG_chapter_tools.asciidoc b/docbook/wsdg_src/WSDG_chapter_tools.asciidoc
index ed2b2d82f9..211d896e44 100644
--- a/docbook/wsdg_src/WSDG_chapter_tools.asciidoc
+++ b/docbook/wsdg_src/WSDG_chapter_tools.asciidoc
@@ -42,8 +42,8 @@ tested.
 Documentation for these tools is outside the scope of this document. If you need
 further information on using a specific tool you should find lots of useful
 information on the web, as these tools are commonly used. You can also get help
-for the UNIX based tools with `toolname --help` or the man page via `man
-toolname`.
+for the UNIX based tools with +**toolname** --help+ or the man page via +man
+**toolname**+.
 
 You will find explanations of the tool usage for some of the specific
 development tasks in <<ChapterSources>>.
@@ -52,7 +52,7 @@ development tasks in <<ChapterSources>>.
 
 Chocolatey is a Windows package manager that can be used to install (and update)
 many of the packages required for Wireshark development. Chocolatey can be
-obtained from the http://chocolatey.org[website] or from a DOS command prompt:
+obtained from the http://chocolatey.org[website] or from a Command Prompt:
 
 ----
 C:\>@powershell -NoProfile -ExecutionPolicy unrestricted -Command "iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin
@@ -65,8 +65,8 @@ PS:\>iex ((new-object net.webclient).DownloadString('https://chocolatey.org/inst
 ----
 
 Chocolatey sometimes installs packages in unexpected locations. Cygwin is a notable
-example -- recent versions of the Cygwin package are installed in `C:\ProgramData\chocolatey\lib\Cygwin\tools\cygwin` instead of Cygwin's default location
-(`C:\cygwin` or `C:\cygwin64`).
+example -- recent versions of the Cygwin package are installed in 'C:\ProgramData\chocolatey\lib\Cygwin\tools\cygwin' instead of Cygwin's default location
+('C:\cygwin' or 'C:\cygwin64').
 
 [[ChToolsCygwin]]
 
@@ -97,7 +97,7 @@ appropriate setup utility to download it. After the download completes,
 run it.
 
 All tools will be installed into one base folder. The default is
-'C:\cygwin' for the 32-bit installer and `C:\cygwin64` for the 64-bit
+'C:\cygwin' for the 32-bit installer and 'C:\cygwin64' for the 64-bit
 installer.
 
 The setup utility will ask you for some settings. The defaults
@@ -118,9 +118,9 @@ After clicking the Next button several times the setup
 will then download and install the selected packages (this may
 take a while, depending on the package size).
 
-Under: 'Start->Programs->Cygwin->Cygwin Bash Shell' you should now be able to start
-a new Cygwin bash shell, which is similar to the standard Windows command line
-interpreters (command.com / cmd.exe) but much more powerful.
+Under menu:Start[Programs,Cygwin,Cygwin Bash Shell] you should now be able to start
+a new Cygwin bash shell, which is similar to the standard Windows Command Prompt
+(cmd.exe) but much more powerful.
 
 [[ChToolsCygwinPackages]]
 
@@ -157,7 +157,7 @@ PS$>choco install cyg-get
 
 Chocolatey installs Cygwin in 'C:\ProgramData\chocolatey\lib\Cygwin\tools\cygwin' by default.
 
-One or more Cygwin packages can be installed using "cyg-get":
+One or more Cygwin packages can be installed using `cyg-get`:
 
 ----
 PS$>cyg-get sed asciidoc
@@ -208,15 +208,15 @@ In particular, the macOS and Windows packages are built using CMake.
 
 Building with CMake typically includes creating a build directory and
 specifying a *generator*, aka a build tool. For example, to build
-Wireshark using Ninja in the directory `wireshark-ninja` you might
+Wireshark using Ninja in the directory 'wireshark-ninja' you might
 run the following commands:
 
 ----
 # Starting from your Wireshark source directory, create a build directory
 # alongside it.
 $ cd ..
-$ mkdir wsbuild
-$ cd wsbuild
+$ mkdir wireshark-ninja
+$ cd wireshark-ninja
 # Assumes your source directory is named "wireshark".
 $ cmake -G Ninja ../wireshark
 $ ninja (or cmake --build .)
@@ -241,11 +241,11 @@ using the `-D` flag. Useful variables and generators include the following:
 
 -DENABLE_APPLICATION_BUNDLE=OFF:: Disable building an application bundle (Wireshark.app) on macOS
 
-You can list all build variables (with help) using `cmake -LH [options]
-../<Name_of_WS_source_dir>`. This lists the cache of build variables
+You can list all build variables (with help) by running *`cmake -LH [options]
+../<Name_of_WS_source_dir>`*. This lists the cache of build variables
 after the cmake run. To only view the current cache, add option `-N`.
 
-After running cmake, you can always run "make help" to see a list of all possible make targets.
+After running cmake, you can always run *`make help`* to see a list of all possible make targets.
 
 Note that CMake honors user umask for creating directories as of now. You should set
 the umask explicitly before running the `install` target.
@@ -367,13 +367,13 @@ Your version string may vary, of course.
 To compile Wireshark on Windows using the Microsoft C/$$C++$$
 compiler, you'll need:
 
-. C compiler (`cl.exe`)
+. C compiler ('cl.exe')
 
-. Assembler (`ml.exe` for 32-bit targets and `ml64.exe` for 64-bit targets)
+. Assembler ('ml.exe' for 32-bit targets and 'ml64.exe' for 64-bit targets)
 
-. Linker (`link.exe`)
+. Linker ('link.exe')
 
-. Resource Compiler (`rc.exe`)
+. Resource Compiler ('rc.exe')
 
 . C runtime headers and libraries (e.g. 'stdio.h', 'msvcrt.lib')
 
@@ -417,7 +417,7 @@ Purchase required?:: http://www.visualstudio.com/en-us/downloads/download-visual
 
 SDK required for 64-bit builds?:: No
 
-CMake Generator: `Visual Studio 12`
+CMake Generator: *`Visual Studio 12`*
 
 .Visual $$C++$$ 2010 Express Edition
 
@@ -427,7 +427,7 @@ Purchase required?:: http://www.microsoft.com/express/Downloads/#Visual_Studio_2
 
 SDK required for 64-bit builds?:: Yes.
 
-CMake Generator: `Visual Studio 10`
+CMake Generator: *`Visual Studio 10`*
 
 Remarks:: Installers created using express editions require a $$C++$$ redistributable
 '$$vcredist_x86.exe$$' (3MB free
@@ -446,7 +446,7 @@ Purchase required?:: Yes
 
 SDK required for 64-bit builds?:: No
 
-CMake Generator: `Visual Studio 10`
+CMake Generator: *`Visual Studio 10`*
 
 Remarks:: Building a 64-bit installer
 requires a a $$C++$$ redistributable
@@ -709,7 +709,7 @@ menu and then click on the required line and press F9.  To run the program,
 press F5.
 
 If you require a non-optimised version, then build using a debug configuration, e.g.
-`msbuild /m /p:Configuration=Debug Wireshark.sln`.  The build products will be found
+*`msbuild /m /p:Configuration=Debug Wireshark.sln`*. The build products will be found
 in C:\Development\wsbuild32\run\Debug\.
 
 [[ChToolsBash]]
@@ -759,7 +759,7 @@ Python 2.5 or later (including Python 3) should work fine and Python 3.5 and
 
 Python is either included or available as a package on most UNIX-like platforms.
 Windows packages and source are available at http://python.org/download/[].
-The Cygwin Python package is *not* recommended since `/usr/bin/python` is
+The Cygwin Python package is *not* recommended since '/usr/bin/python' is
 a symbolic link, which causes confusion outside Cygwin.
 
 You can also use Chocolatey to install Python:
@@ -842,7 +842,7 @@ Perl may be copied only under the terms of either the Artistic License or the
 GNU General Public License, which may be found in the Perl 5 source kit.
 
 Complete documentation for Perl, including FAQ lists, should be found on
-this system using `man perl' or `perldoc perl'.  If you have access to the
+this system using *`man perl'* or *`perldoc perl'*.  If you have access to the
 Internet, point your browser at http://www.perl.com/, the Perl Home Page.
 ----
 
@@ -934,7 +934,7 @@ Your version string may vary.
 
 A native Windows version of bison is available in the _winflexbison_
 https://chocolatey.org/[Chocolatey] package. Note that the executable is named
-`win_bison`.
+'win_bison'.
 
 Native packages are available from other sources such as
 http://gnuwin32.sourceforge.net/packages/bison.htm[GnuWin]. They aren't
@@ -977,7 +977,7 @@ Your version string may vary.
 
 A native Windows version of flex is available in the _winflexbison_
 https://chocolatey.org/[Chocolatey] package. Note that the executable is named
-`win_flex`.
+'win_flex'.
 
 ----
 PS:\>choco install winflexbison
diff --git a/docbook/wsdg_src/WSDG_preface.asciidoc b/docbook/wsdg_src/WSDG_preface.asciidoc
index 21cec67736..c3f62c4b67 100644
--- a/docbook/wsdg_src/WSDG_preface.asciidoc
+++ b/docbook/wsdg_src/WSDG_preface.asciidoc
@@ -69,27 +69,6 @@ and updated for VS2013 by mailto:{wsdg-author-email2}[Graham Bloice]
 
 It is written in AsciiDoc.
 
-You will find some specially marked parts in this book:
-
-[WARNING]
-.This is a warning
-====
-You should pay attention to a warning, as otherwise data loss might occur.
-====
-
-[NOTE]
-.This is a note
-====
-A note will point you to common mistakes and things that might not be
-obvious.
-====
-
-[TIP]
-.This is a tip
-====
-Tips will be helpful for your everyday work developing Wireshark.
-====
-
 [[PreDownload]]
 
 === Where to get the latest copy of this document?
diff --git a/docbook/wsug_src/WSUG_preface.asciidoc b/docbook/wsug_src/WSUG_preface.asciidoc
index 507a9203f4..959d86f9b1 100644
--- a/docbook/wsug_src/WSUG_preface.asciidoc
+++ b/docbook/wsug_src/WSUG_preface.asciidoc
@@ -79,26 +79,6 @@ updated by mailto:{wsug-author-email}[Ulf Lamping].
 It was originally written in DocBook/XML and converted to AsciiDoc by
 Gerald Combs.
 
-You will find some specially marked parts in this book:
-
-[WARNING]
-.This is a warning
-====
-You should pay attention to a warning, otherwise data loss might occur.
-====
-
-[NOTE]
-.This is a note
-====
-A note will point you to common mistakes and things that might not be obvious.
-====
-
-[TIP]
-.This is a tip
-====
-Tips are helpful for your everyday work using Wireshark.
-====
-
 [[PreDownload]]
 
 === Where to get the latest copy of this document?