WSUG: Convert the "User Interface" chapter to AsciiDoc.

Add the "asciidoc.conf" compatibility configuration file from
Asciidoctor. Although we don't use Asciidoctor it gives us macros that
keep us from losing some useful DocBook elements. Update various CMake
files to support multiple AsciiDoc configuration files.

Leave most of the content intact for now. Hopefully the other chapters
aren't as laden with markup.

Change-Id: Id69757342b86abb2b3130cb61e90f5695a26ea8a
Reviewed-on: https://code.wireshark.org/review/3680
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot <buildbot-no-reply@wireshark.org>
Reviewed-by: Gerald Combs <gerald@wireshark.org>

1 files changed, 398 insertions, 0 deletions

diff --git a/docbook/asciidoctor-asciidoc.conf b/docbook/asciidoctor-asciidoc.conf
new file mode 100644
index 0000000000..ad3409aa53
--- /dev/null
+++ b/docbook/asciidoctor-asciidoc.conf
@@ -0,0 +1,398 @@
+# This file is an AsciiDoc configuration file that makes
+# AsciiDoc conform with Asciidoctor's fixes and customizations.
+#
+# Place this file in the same directory as your AsciiDoc document and the
+# AsciiDoc processor (asciidoc) will automatically use it.
+
+# Copied from from https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/compat/asciidoc.conf
+# AsciiDoctor is available under the MIT license.
+
+[miscellaneous]
+newline=\n
+
+[attributes]
+# make html5 the default html backend
+backend-alias-html=html5
+apostrophe='
+asterisk=*
+backtick=`
+brvbar=¦
+caret=^
+# plus introduced in AsciiDoc 8.6.9
+plus=+
+space=" "
+tilde=~
+user-home={eval:os.path.expanduser('~')}
+vbar=|
+# NOTE use -a no-inline-literal to set compat-mode to default when using AsciiDoc Python
+ifndef::no-inline-literal[]
+compat-mode=legacy
+endif::[]
+
+[replacements]
+# right single quote
+(?<!\\)`'=&#8217;
+# escaped right single quote
+\\`'=`'
+
+[quotes]
+# disable single quotes as constrained formatting marks for emphasis
+# this change can also be made in the document using the attribute entry :quotes.':
+ifdef::compat-mode[]
+'=
++=
+++=
+`=
+``=#monospaced
+`|`=monospaced
+\##=#mark
+\#=mark
+endif::[]
+
+# enables markdown-style headings
+[titles]
+sect0=^(=|#) +(?P<title>[\S].*?)(?: +\1)?$
+sect1=^(==|##) +(?P<title>[\S].*?)(?: +\1)?$
+sect2=^(===|###) +(?P<title>[\S].*?)(?: +\1)?$
+sect3=^(====|####) +(?P<title>[\S].*?)(?: +\1)?$
+sect4=^(=====|#####) +(?P<title>[\S].*?)(?: +\1)?$
+sect5=^(======|######) +(?P<title>[\S].*?)(?: +\1)?$
+
+# Disable subs on pass block by default
+[blockdef-pass]
+subs=none
+
+# enables fenced code blocks
+# FIXME I haven't sorted out yet how to do syntax highlighting
+[blockdef-fenced-code]
+delimiter=^```(?:\w+(?:,numbered)?)?$
+ifdef::language[]
+style=source
+template::[source-filter-style]
+endif::language[]
+ifndef::language[]
+template=listingblock
+subs=verbatim
+posattrs=style
+endif::language[]
+
+# enables blockquotes to be defined using two double quotes
+[blockdef-air-quote]
+template::[blockdef-quote]
+delimiter=^""$
+
+# markdown-style blockquote (paragraph only)
+# FIXME does not strip leading > on subsequent lines
+[paradef-markdown-quote]
+delimiter=(?s)>\s*(?P<text>\S.*)
+style=quote
+quote-style=template="quoteparagraph",posattrs=("style","attribution","citetitle")
+
+# fix regex for callout list to require number; also makes markdown-style blockquote work
+[listdef-callout]
+posattrs=style
+delimiter=^<?(?P<index>\d+>) +(?P<text>.+)$
+type=callout
+tags=callout
+style=arabic
+
+# enables literal block to be used as source block
+[blockdef-literal]
+template::[source-filter-style]
+
+# enables source block when source-highlighter is not defined
+ifndef::source-highlighter[]
+[source-filter-style]
+source-style=template="listingblock",subs=("specialcharacters","callouts"),posattrs=("style","language","src_numbered","src_tab")
+
+[paradef-default]
+template::[source-filter-style]
+
+[paradef-literal]
+template::[source-filter-style]
+
+[blockdef-open]
+template::[source-filter-style]
+
+[blockdef-listing]
+template::[source-filter-style]
+endif::source-highlighter[]
+
+[tabledef-csv]
+template::[tabledef-default]
+delimiter=^,={3,}$
+format=csv
+
+[tabledef-dsv]
+template::[tabledef-default]
+delimiter=^:={3,}$
+format=dsv
+
+[macros]
+ifdef::no-inline-literal[]
+(?su)\\?\+\+(?P<passtext>.*?)\+\+=pass[specialcharacters]
+(?su)(?<![+\w])(\\?\+(?P<passtext>\S|\S.*?\S)\+)(?![+\w])=pass[specialcharacters]
+endif::no-inline-literal[]
+
+# additional callout match behind line comments
+#(?://|#|;;) ?\((?P<index>\d+)\)=callout
+# additional callout match for XML
+[\\]?&lt;!--(?P<index>\d+)--&gt;=callout
+
+# --- or *** or ___ or - - - or * * * or _ _ _ (in addition to the built-in ''')
+^ {0,3}([-\*_])( *)\1\2\1$=#ruler
+
+# button:[Save]
+(?su)(?<!\w)\\?button:\[(?P<attrlist>(?:\\\]|[^\]])+?)\]=button
+
+# kbd:[F11] or kbd:[Ctrl+T] or kbd:[Ctrl,T]
+(?su)(?<!\w)\\?kbd:\[(?P<attrlist>(?:\\\]|[^\]])+?)\]=keyboard
+
+# menu:Search[] or menu:File[New...] or menu:View[Page Style, No Style]
+# TODO implement menu:View[Page Style > No Style] syntax
+(?su)(?<!\w)[\\]?(?P<name>menu):(?P<target>\w|\w.*?\S)?\[(?P<attrlist>.*?)\]=
+
+ifdef::basebackend-html[]
+
+[sect5]
+<div class="sect5{style? {style}}{role? {role}}">
+<h6{id? id="{id}"}>{title}</h6>
+|
+</div>
+
+[button-inlinemacro]
+<b class="button">{1}</b>
+
+[keyboard-inlinemacro]
+{set2:keys:{eval:re.split(r'(?<!\+ |.\+)\+', '{1}')}}
+{2%}{eval:len({keys}) == 1}<kbd>{1}</kbd>
+{2%}{eval:len({keys}) == 2}<kbd class="combo"><kbd>{eval:{keys}[0].strip()}</kbd>+<kbd>{eval:{keys}[1].strip()}</kbd></kbd>
+{2%}{eval:len({keys}) == 3}<kbd class="combo"><kbd>{eval:{keys}[0].strip()}</kbd>+<kbd>{eval:{keys}[1].strip()}</kbd>+<kbd>{eval:{keys}[2].strip()}</kbd></kbd>
+{2#}{3%}<kbd class="combo"><kbd>{1}</kbd>+<kbd>{2}</kbd></kbd>
+{3#}<kbd class="combo"><kbd>{1}</kbd>+<kbd>{2}</kbd>+<kbd>{3}</kbd></kbd>
+
+[menu-inlinemacro]
+{1%}<span class="menu">{target}</span>
+{1#}{2%}<span class="menuseq"><span class="menu">{target}</span>&#160;&#9656; <span class="menuitem">{1}</span></span>
+{2#}{3%}<span class="menuseq"><span class="menu">{target}</span>&#160;&#9656; <span class="submenu">{1}</span>&#160;&#9656; <span class="menuitem">{2}</span></span>
+{3#}<span class="menuseq"><span class="menu">{target}</span>&#160;&#9656; <span class="submenu">{1}</span>&#160;&#9656; <span class="submenu">{2}</span>&#160;&#9656; <span class="menuitem">{3}</span></span>
+
+[literal-inlinemacro]
+<code>{passtext}</code>
+
+[tags]
+emphasis=<em{1? class="{1}"}>|</em>
+strong=<strong{1? class="{1}"}>|</strong>
+monospaced=<code{1? class="{1}"}>|</code>
+superscript=<sup{1? class="{1}"}>|</sup>
+subscript=<sub{1? class="{1}"}>|</sub>
+mark={1=<mark>}{1?<span class="{1}">}|{1?</span>}{1=</mark>}
+
+[monospacedwords]
+<code>{words}</code>
+
+ifdef::linkattrs[]
+[http-inlinemacro]
+<a href="{name}:{target}"{id? id="{id}"}{role? class="{role}"}{window? target="{window}"}>{1={name}:{target}}</a>
+[https-inlinemacro]
+<a href="{name}:{target}"{id? id="{id}"}{role? class="{role}"}{window? target="{window}"}>{1={name}:{target}}</a>
+[ftp-inlinemacro]
+<a href="{name}:{target}"{id? id="{id}"}{role? class="{role}"}{window? target="{window}"}>{1={name}:{target}}</a>
+[file-inlinemacro]
+<a href="{name}:{target}"{id? id="{id}"}{role? class="{role}"}{window? target="{window}"}>{1={name}:{target}}</a>
+[irc-inlinemacro]
+<a href="{name}:{target}"{id? id="{id}"}{role? class="{role}"}{window? target="{window}"}>{1={name}:{target}}</a>
+[mailto-inlinemacro]
+<a href="mailto:{target}"{id? id="{id}"}{role? class="{role}"}{window? target="{window}"}>{1={target}}</a>
+[link-inlinemacro]
+<a href="{target}"{id? id="{id}"}{role? class="{role}"}{window? target="{window}"}>{1={target}}</a>
+endif::linkattrs[]
+
+[listtags-numbered]
+list=<div class="olist{style? {style}}{compact-option? compact}{role? {role}}"{id? id="{id}"}>{title?<div class="title">{title}</div>}<ol class="{style}"{style@loweralpha: type="a"}{style@lowerroman: type="i"}{style@upperalpha: type="A"}{style@upperroman: type="I"}{start? start="{start}"}>|</ol></div>
+
+[tabletags-monospaced]
+paragraph=<p class="tableblock"><code>|</code></p>
+
+[sect0]
+<h1{id? id="{id}"} class="sect0">{title}</h1>
+|
+
+# support for document title in embedded documents
+ifeval::[not config.header_footer]
+[preamble]
+<h1>{title={doctitle}}</h1>{set:title-rendered:}
+<div id="preamble">
+<div class="sectionbody">
+|
+</div>
+{toc,toc2#}{toc-placement$preamble:}{template:toc}
+</div>
+
+[sect1]
+{title-rendered%}<h1>{doctitle}</h1>
+<div class="sect1{style? {style}}{role? {role}}">
+<h2{id? id="{id}"}>{numbered?{sectnum} }{title}</h2>
+<div class="sectionbody">
+|
+</div>
+</div>
+endif::[]
+
+# override to add the admonition name to the class attribute of the outer element
+[admonitionblock]
+<div class="admonitionblock {name}{role? {role}}{unbreakable-option? unbreakable}"{id? id="{id}"}>
+<table><tr>
+<td class="icon">
+{data-uri%}{icons#}<img src="{icon={iconsdir}/{name}.png}" alt="{caption}">
+{data-uri#}{icons#}<img alt="{caption}" src="data:image/png;base64,
+{data-uri#}{icons#}{sys:"{python}" -u -c "import base64,sys; base64.encode(sys.stdin,sys.stdout)" < "{eval:os.path.join(r"{indir={outdir}}",r"{icon={iconsdir}/{name}.png}")}"}">
+{icons%}<div class="title">{caption}</div>
+</td>
+<td class="content">
+<div class="title">{title}</div>
+|
+</td>
+</tr></table>
+</div>
+
+# modified so that:
+# a. imagesdir is only prepended if target is not a uri or absolute path (relative path only)
+# b. automatic alt text is calculated from basename of target without extension
+# note that the escaped_target attribute must be set in order to use a uri in the conditional attribute reference
+[image-inlinemacro]
+<span class="image{role? {role}}"{float? style="float: {float}"}>{set2:escaped_target:{eval:'{target}'.replace(':','\:')}}
+<a class="image" href="{link}">
+{data-uri%}<img src="{target@^(/|https?\://).*:{escaped_target}:{imagesdir?{imagesdir}}{imagesdir?/}{escaped_target}}" alt="{alt={eval:os.path.splitext(os.path.basename('{target}'))[0]}}"{width? width="{width}"}{height? height="{height}"}{title? title="{title}"}>
+{data-uri#}<img alt="{alt={target}}"{width? width="{width}"}{height? height="{height}"}{title? title="{title}"}
+{data-uri#}{sys:"{python}" -u -c "import mimetypes,base64,sys; print 'src=\"data:'+mimetypes.guess_type(r'{target}')[0]+';base64,'; base64.encode(sys.stdin,sys.stdout)" < "{eval:os.path.join(r"{indir={outdir}}",r"{imagesdir=}",r"{target}")}"}">
+{link#}</a>
+</span>
+
+# modified so that:
+# a. imagesdir is only prepended if target is not a uri or absolute path (relative path only)
+# b. automatic alt text is calculated from basename of target without extension
+# note that the escaped_target attribute must be set in order to use a uri in the conditional attribute reference
+[image-blockmacro]
+<div class="imageblock{style? {style}}{role? {role}}{unbreakable-option? unbreakable}"{id? id="{id}"}{align? style="text-align:{align};"}{float? style="float: {float}"}>
+<div class="content">{set2:escaped_target:{eval:'{target}'.replace(':','\:')}}
+<a class="image" href="{link}">
+{data-uri%}<img src="{target@^(/|https?\://).*:{escaped_target}:{imagesdir?{imagesdir}}{imagesdir?/}{escaped_target}}" alt="{alt={eval:os.path.splitext(os.path.basename('{target}'))[0]}}"{width? width="{width}"}{height? height="{height}"}>
+{data-uri#}<img alt="{alt={target}}"{width? width="{width}"}{height? height="{height}"}
+{data-uri#}{sys:"{python}" -u -c "import mimetypes,base64,sys; print 'src=\"data:'+mimetypes.guess_type(r'{target}')[0]+';base64,'; base64.encode(sys.stdin,sys.stdout)" < "{eval:os.path.join(r"{indir={outdir}}",r"{imagesdir=}",r"{target}")}"}">
+{link#}</a>
+</div>
+<div class="title">{caption={figure-caption} {counter:figure-number}. }{title}</div>
+</div>
+
+# a common template for emitting the attribute for a quote or verse block
+# don't output attribution div if attribution or citetitle are both empty
+[attribution]
+{attribution,citetitle#}<div class="attribution">
+&#8212; {attribution}{citetitle?<br>}
+<cite>{citetitle}</cite>
+{attribution,citetitle#}</div>
+
+# override to use blockquote element for content and cite element for cite title
+[quoteblock]
+<div class="quoteblock{role? {role}}{unbreakable-option? unbreakable}"{id? id="{id}"}>
+<div class="title">{title}</div>
+<blockquote>
+|
+</blockquote>
+template::[attribution]
+</div>
+
+# override to use cite element for cite title
+[verseblock]
+<div class="verseblock{role? {role}}{unbreakable-option? unbreakable}"{id? id="{id}"}>
+<div class="title">{title}</div>
+<pre class="content">
+|
+</pre>
+template::[attribution]
+</div>
+
+# override tabletags to support cellbgcolor
+[tabletags-default]
+headdata=<th class="tableblock halign-{halign=left} valign-{valign=top}"{colspan@1:: colspan="{colspan}"}{rowspan@1:: rowspan="{rowspan}"}{cellbgcolor? style="background-color:{cellbgcolor};"}>|</th>
+bodydata=<td class="tableblock halign-{halign=left} valign-{valign=top}"{colspan@1:: colspan="{colspan}"}{rowspan@1:: rowspan="{rowspan}"}{cellbgcolor? style="background-color:{cellbgcolor};"}>|</td>
+
+# override header cells to use th
+[tabletags-header]
+bodydata=<th class="tableblock halign-{halign=left} valign-{valign=top}" {colspan@1::colspan="{colspan}" }{rowspan@1::rowspan="{rowspan}" }>|</th>
+paragraph=<p class="tableblock">|</p>
+
+[toc]
+<div id="toc">
+<div id="toctitle">{toc-title}</div>
+ifdef::toc2[]
+<script type="text/javascript">
+document.body.className += ' toc2';
+document.getElementById('toc').className = 'toc2';
+</script>
+endif::toc2[]
+<noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
+</div>
+
+endif::basebackend-html[]
+
+# Override docinfo to support subtitle
+ifdef::basebackend-docbook[]
+
+[sect5]
+<section{id? id="{id}"}{role? role="{role}"}{reftext? xreflabel="{reftext}"}>
+<title>{title}</title>
+|
+</section>
+
+[tags]
+monospaced=<literal{1? role="{1}"}>|</literal>
+subscript=<subscript{1? role="{1}"}>|</subscript>
+superscript=<superscript{1? role="{1}"}>|</superscript>
+
+[button-inlinemacro]
+<guibutton>{1}</guibutton>
+
+[keyboard-inlinemacro]
+{set2:keys:{eval:re.split(r'(?<!\+ |.\+)\+', '{1}')}}
+{2%}{eval:len({keys}) == 1}<keycap>{1}</keycap>
+{2%}{eval:len({keys}) == 2}<keycombo><keycap>{eval:{keys}[0].strip()}</keycap><keycap>{eval:{keys}[1].strip()}</keycap></keycombo>
+{2%}{eval:len({keys}) == 3}<keycombo><keycap>{eval:{keys}[0].strip()}</keycap><keycap>{eval:{keys}[1].strip()}</keycap><keycap>{eval:{keys}[2].strip()}</keycap></keycombo>
+{2#}{3%}<keycombo><keycap>{1}</keycap><keycap>{2}</keycap></keycombo>
+{3#}<keycombo><keycap>{1}</keycap><keycap>{2}</keycap><keycap>{3}</keycap></keycombo>
+
+[menu-inlinemacro]
+{1%}<guimenu>{target}</guimenu>
+{1#}{2%}<menuchoice><guimenu>{target}</guimenu> <guimenuitem>{1}</guimenuitem></menuchoice>
+{2#}{3%}<menuchoice><guimenu>{target}</guimenu> <guisubmenu>{1}</guisubmenu> <guimenuitem>{2}</guimenuitem></menuchoice>
+{3#}<menuchoice><guimenu>{target}</guimenu> <guisubmenu>{1}</guisubmenu> <guisubmenu>{2}</guisubmenu> <guimenuitem>{3}</guimenuitem></menuchoice>
+
+# override tabletags to support cellbgcolor
+[tabletags-default]
+headdata=<entry align="{halign}" valign="{valign}"{colspan@1:: namest="col_{colstart}" nameend="col_{colend}"}{morerows@0:: morerows="{morerows}"}>{cellbgcolor?<?dbfo bgcolor="{cellbgcolor}"?>}|</entry>
+bodydata=<entry align="{halign}" valign="{valign}"{colspan@1:: namest="col_{colstart}" nameend="col_{colend}"}{morerows@0:: morerows="{morerows}"}>{cellbgcolor?<?dbfo bgcolor="{cellbgcolor}"?>}|</entry>
+
+[docinfo]
+ifndef::notitle[]
+{set2:subtitle_offset:{eval:'{doctitle}'.rfind(': ')}}
+{eval:{subtitle_offset} != -1}<title>{eval:'{doctitle}'[0:{subtitle_offset}]}</title>
+{eval:{subtitle_offset} != -1}<subtitle>{eval:'{doctitle}'[{subtitle_offset} + 2:]}</subtitle>
+{eval:{subtitle_offset} < 0}<title>{doctitle}</title>
+endif::notitle[]
+<date>{revdate}</date>
+# To ensure valid articleinfo/bookinfo when there is no AsciiDoc header.
+{doctitle%}{revdate%}<date>{docdate}</date>
+{authored#}<author>
+<firstname>{firstname}</firstname>
+<othername>{middlename}</othername>
+<surname>{lastname}</surname>
+<email>{email}</email>
+{authored#}</author>
+<authorinitials>{authorinitials}</authorinitials>
+<revhistory><revision>{revnumber?<revnumber>{revnumber}</revnumber>}<date>{revdate}</date>{authorinitials?<authorinitials>{authorinitials}</authorinitials>}{revremark?<revremark>{revremark}</revremark>}</revision></revhistory>
+{docinfo1,docinfo2#}{include:{docdir}/docinfo.xml}
+{docinfo,docinfo2#}{include:{docdir}/{docname}-docinfo.xml}
+<orgname>{orgname}</orgname>
+
+endif::basebackend-docbook[]