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>

3 files changed, 48 insertions, 69 deletions

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?