docs/pandoc: Don't escape underscores in the middle of text

Pandoc deliberately (and contrary to markdown) doesn't treat underscores in
the middle of normal text as emphasis markers, as this is almost always the
unhelpful interpretation.

For text which is emphasised using _, an underscore in the middle is
interpreted, but the emphasis marker can be switched to * instead.

One problem case is where we use {} globbing with identifier names, as it
counts as a word break.  Therefore, we do need to retain the escaped
underscore immediately following a closing brace.

No change in content - only formatting.  This results in the text being easier
to read and grep.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

docs/features/feature-levelling.pandoc

@@ -127,19 +127,19 @@ time.
 ## Host boot
 
 As Xen boots, it will enumerate the features it can see.  This is stored as
-the _raw\_featureset_.
+the *raw_featureset*.
 
 Errata checks and command line arguments are then taken into account to reduce
-the _raw\_featureset_ into the _host\_featureset_, which is the set of
+the *raw_featureset* into the *host_featureset*, which is the set of
 features Xen uses.  On hardware with masking/override MSRs, the default MSR
-values are picked from the _host\_featureset_.
+values are picked from the *host_featureset*.
 
-The _host\_featureset_ is then used to calculate the _pv\_featureset_ and
-_hvm\_featureset_, which are the maximum featuresets Xen is willing to offer
+The *host_featureset* is then used to calculate the *pv_featureset* and
+*hvm_featureset*, which are the maximum featuresets Xen is willing to offer
 to PV and HVM guests respectively.
 
 In addition, Xen will calculate how much control it has over non-cooperative
-PV `CPUID` instructions, storing this information as _levelling\_caps_.
+PV `CPUID` instructions, storing this information as *levelling_caps*.
 
 ## Domain creation
 
@@ -163,7 +163,7 @@ features will be able to find some of them.  e.g. There is no way of forcibly
 preventing a guest from using 1GB superpages if the hardware supports it.
 
 Some information simply cannot be hidden from guests.  There is no way to
-control certain behaviour such as the hardware MXCSR\_MASK or x87 FPU exception
+control certain behaviour such as the hardware MXCSR_MASK or x87 FPU exception
 behaviour.
 
 
@@ -196,7 +196,7 @@ be at the head of the migration stream.
 
 MSRs are another source of features for guests.  There is no general provision
 for controlling the available MSRs.  E.g. 64bit versions of Windows notice
-changes in IA32\_MISC\_ENABLE, and suffer a BSOD 0x109 (Critical Structure
+changes in IA32_MISC_ENABLE, and suffer a BSOD 0x109 (Critical Structure
 Corruption)
 
 

docs/features/migration.pandoc

@@ -65,7 +65,7 @@ legacy stream into a migration v2 stream.
 
 ## libxl
 
-With migration v2 support, LIBXL\_HAVE\_SRM\_V2 and LIBXL\_HAVE\_SRM\_V1
+With migration v2 support, LIBXL_HAVE_SRM_V2 and LIBXL_HAVE_SRM_V1
 are introduced to indicate support.  `domain_restore_params` gains a new
 parameter, `stream_version`, which is used to distinguish between legacy and
 v2 migration streams, and hence whether legacy conversion is required.

docs/features/sched_credit2.pandoc

@@ -57,7 +57,7 @@ is all contained in `xen/common/sched_credit2.c`.
 
 Global scheduling parameters, such as context switching rate
 limiting, is only available from Xen 4.8 onward. In libxl, the
-`LIBXL\_HAVE\_SCHED\_CREDIT2\_PARAMS` symbol is introduced to
+LIBXL_HAVE_SCHED_CREDIT2_PARAMS symbol is introduced to
 indicate their availability.
 
 # Testing
@@ -82,8 +82,8 @@ following:
 * vCPUs' reservations (similar to caps, but providing a vCPU with guarantees
   about some pCPU time it will always be able to execute for);
 * benchmarking for assessing the best combination of values for the various
-  parameters (`sched\_credit2\_migrate\_resist`, `credit2\_balance\_over`,
-  `credit2\_balance\_under`)
+  parameters (`sched_credit2_migrate_resist`, `credit2_balance_over`,
+  `credit2_balance_under`)
 
 # Known issues
 

docs/features/sched_rtds.pandoc

@@ -49,12 +49,12 @@ hook based, architecture for schedulers. Thanks to this, RTDS code
 is all contained in `xen/common/sched_rtds.c`.
 
 In libxl, the availability of the RTDS scheduler is advertised by
-the presence of the LIBXL\_HAVE\_SCHED\_RTDS symbol. The ability of
+the presence of the LIBXL_HAVE_SCHED_RTDS symbol. The ability of
 specifying different scheduling parameters for each vcpu has been
 introduced later, and is available if the following symbols are defined:
-    * `LIBXL\_HAVE\_VCPU\_SCHED\_PARAMS`,
-    * `LIBXL\_HAVE\_SCHED\_RTDS\_VCPU\_PARAMS`,
-    * `LIBXL\_HAVE\_SCHED\_RTDS\_VCPU\_EXTRA`.
+    * LIBXL_HAVE_VCPU_SCHED_PARAMS,
+    * LIBXL_HAVE_SCHED_RTDS_VCPU_PARAMS,
+    * LIBXL_HAVE_SCHED_RTDS_VCPU_EXTRA.
 
 # Limitations
 

docs/specs/libxc-migration-stream.pandoc

@@ -298,14 +298,14 @@ count       Number of pages described in this record.
 
 pfn         An array of count PFNs and their types.
 
-            Bit 63-60: XEN\_DOMCTL\_PFINFO\_* type (from
+            Bit 63-60: XEN_DOMCTL_PFINFO_* type (from
             `public/domctl.h` but shifted by 32 bits)
 
             Bit 59-52: Reserved.
 
             Bit 51-0: PFN.
 
-page\_data  page\_size octets of uncompressed page contents for each
+page_data   page_size octets of uncompressed page contents for each
             page set as present in the pfn array.
 --------------------------------------------------------------------
 
@@ -342,7 +342,7 @@ XALLOC         0xE        Allocate only.
 XTAB           0xF        Invalid page.
 --------------------------------------------------------------------
 
-Table: XEN\_DOMCTL\_PFINFO\_* Page Types.
+Table: XEN_DOMCTL_PFINFO_* Page Types.
 
 PFNs with type `BROKEN`, `XALLOC`, or `XTAB` do not have any
 corresponding `page_data`.
@@ -429,13 +429,13 @@ context          Binary data for this VCPU.
 ---------------------------------------------------------------------
 Record type                  Accessor hypercalls
 -----------------------      ----------------------------------------
-X86\_PV\_VCPU\_BASIC         XEN\_DOMCTL\_{get,set}vcpucontext
+X86_PV_VCPU_BASIC            XEN_DOMCTL_{get,set}vcpucontext
 
-X86\_PV\_VCPU\_EXTENDED      XEN\_DOMCTL\_{get,set}\_ext\_vcpucontext
+X86_PV_VCPU_EXTENDED         XEN_DOMCTL_{get,set}\_ext_vcpucontext
 
-X86\_PV\_VCPU\_XSAVE         XEN\_DOMCTL\_{get,set}vcpuextstate
+X86_PV_VCPU_XSAVE            XEN_DOMCTL_{get,set}vcpuextstate
 
-X86\_PV\_VCPU\_MSRS          XEN\_DOMCTL\_{get,set}\_vcpu\_msrs
+X86_PV_VCPU_MSRS             XEN_DOMCTL_{get,set}\_vcpu_msrs
 ---------------------------------------------------------------------
 
 \clearpage
@@ -464,7 +464,7 @@ TSC_INFO
 --------
 
 Domain TSC information, as accessed by the
-XEN\_DOMCTL\_{get,set}tscinfo hypercall sub-ops.
+XEN_DOMCTL_{get,set}tscinfo hypercall sub-ops.
 
      0     1     2     3     4     5     6     7 octet
     +------------------------+------------------------+
@@ -478,7 +478,7 @@ XEN\_DOMCTL\_{get,set}tscinfo hypercall sub-ops.
 --------------------------------------------------------------------
 Field            Description
 -----------      ---------------------------------------------------
-mode             TSC mode, TSC\_MODE\_* constant.
+mode             TSC mode, TSC_MODE_* constant.
 
 khz              TSC frequency, in kHz.
 
@@ -493,7 +493,7 @@ HVM_CONTEXT
 -----------
 
 HVM Domain context, as accessed by the
-XEN\_DOMCTL\_{get,set}hvmcontext hypercall sub-ops.
+XEN_DOMCTL_{get,set}hvmcontext hypercall sub-ops.
 
      0     1     2     3     4     5     6     7 octet
     +-------------------------------------------------+
@@ -513,7 +513,7 @@ HVM_PARAMS
 ----------
 
 HVM Domain parameters, as accessed by the
-HVMOP\_{get,set}\_param hypercall sub-ops.
+HVMOP_{get,set}\_param hypercall sub-ops.
 
      0     1     2     3     4     5     6     7 octet
     +------------------------+------------------------+
@@ -643,25 +643,25 @@ A typical save record for an x86 PV guest image would look like:
 
 1. Image header
 2. Domain header
-3. X86\_PV\_INFO record
-4. X86\_PV\_P2M\_FRAMES record
-5. Many PAGE\_DATA records
-6. TSC\_INFO
-7. SHARED\_INFO record
+3. X86_PV_INFO record
+4. X86_PV_P2M_FRAMES record
+5. Many PAGE_DATA records
+6. TSC_INFO
+7. SHARED_INFO record
 8. VCPU context records for each online VCPU
-    a. X86\_PV\_VCPU\_BASIC record
-    b. X86\_PV\_VCPU\_EXTENDED record
-    c. X86\_PV\_VCPU\_XSAVE record
-    d. X86\_PV\_VCPU\_MSRS record
+    a. X86_PV_VCPU_BASIC record
+    b. X86_PV_VCPU_EXTENDED record
+    c. X86_PV_VCPU_XSAVE record
+    d. X86_PV_VCPU_MSRS record
 9. END record
 
 There are some strict ordering requirements.  The following records must
 be present in the following order as each of them depends on information
 present in the preceding ones.
 
-1. X86\_PV\_INFO record
-2. X86\_PV\_P2M\_FRAMES record
-3. PAGE\_DATA records
+1. X86_PV_INFO record
+2. X86_PV_P2M_FRAMES record
+3. PAGE_DATA records
 4. VCPU records
 
 x86 HVM Guest
@@ -671,12 +671,12 @@ A typical save record for an x86 HVM guest image would look like:
 
 1. Image header
 2. Domain header
-3. Many PAGE\_DATA records
-4. TSC\_INFO
-5. HVM\_PARAMS
-6. HVM\_CONTEXT
+3. Many PAGE_DATA records
+4. TSC_INFO
+5. HVM_PARAMS
+6. HVM_CONTEXT
 
-HVM\_PARAMS must precede HVM\_CONTEXT, as certain parameters can affect
+HVM_PARAMS must precede HVM_CONTEXT, as certain parameters can affect
 the validity of architectural state in the context.
 
 
@@ -731,5 +731,5 @@ Errata
 
 1. For compatibility with older code, the receving side of a stream should
    tolerate and ignore variable sized records with zero content.  Xen releases
-   between 4.6 and 4.8 could end up generating valid HVM\_PARAMS or
-   X86\_PV\_VCPU\_{EXTENDED,XSAVE,MSRS} records with zero-length content.
+   between 4.6 and 4.8 could end up generating valid HVM_PARAMS or
+   X86_PV_VCPU_{EXTENDED,XSAVE,MSRS} records with zero-length content.

docs/specs/libxl-migration-stream.pandoc

@@ -182,8 +182,8 @@ in the stream.
 
 The end record contains no fields; its body_length is 0.
 
-LIBXC\_CONTEXT
---------------
+LIBXC_CONTEXT
+-------------
 
 A libxc context record is a marker, indicating that the stream should be
 handed to `xc_domain_restore()`.  `libxc` shall be responsible for reading its
@@ -199,8 +199,8 @@ The libxc context record contains no fields; its body_length is 0[^1].
 might write into the stream, especially for live migration where the quantity
 of data is partially proportional to the elapsed time.
 
-EMULATOR\_XENSTORE\_DATA
-------------------------
+EMULATOR_XENSTORE_DATA
+----------------------
 
 A set of xenstore key/value pairs for a specific emulator associated with the
 domain.
@@ -226,7 +226,7 @@ domain.  At the time of writing, keys are relative to the path
 although this path is free to change moving forward, thus should not be
 assumed.
 
-EMULATOR\_CONTEXT
+EMULATOR_CONTEXT
 ----------------
 
 A context blob for a specific emulator associated with the domain.
@@ -242,8 +242,8 @@ A context blob for a specific emulator associated with the domain.
 The *emulator_ctx* is a binary blob interpreted by the emulator identified by
 *emulator_id*.  Its format is unspecified.
 
-CHECKPOINT\_END
----------------
+CHECKPOINT_END
+--------------
 
 A checkpoint end record marks the end of a checkpoint in the image.
 
@@ -253,8 +253,8 @@ A checkpoint end record marks the end of a checkpoint in the image.
 The end record contains no fields; its body_length is 0.
 
 
-CHECKPOINT\_STATE
---------------
+CHECKPOINT_STATE
+----------------
 
 A checkpoint state record contains the control information for checkpoint. It
 is only used by COLO, more detail please reference README.colo.
@@ -282,26 +282,26 @@ In COLO, Primary is running in below loop:
 
 1. Suspend primary vm
     a. Suspend primary vm
-    b. Read _CHECKPOINT\_SVM\_SUSPENDED_ sent by secondary
+    b. Read *CHECKPOINT_SVM_SUSPENDED* sent by secondary
 2. Checkpoint
 3. Resume primary vm
-    a. Read _CHECKPOINT\_SVM\_READY_ from secondary
+    a. Read *CHECKPOINT_SVM_READY* from secondary
     b. Resume primary vm
-    c. Read _CHECKPOINT\_SVM\_RESUMED_ from secondary
+    c. Read *CHECKPOINT_SVM_RESUMED* from secondary
 4. Wait a new checkpoint
-    a. Send _CHECKPOINT\_NEW_ to secondary
+    a. Send *CHECKPOINT_NEW* to secondary
 
 While Secondary is running in below loop:
 
 1. Resume secondary vm
-    a. Send _CHECKPOINT\_SVM\_READY_ to primary
+    a. Send *CHECKPOINT_SVM_READY* to primary
     b. Resume secondary vm
-    c. Send _CHECKPOINT\_SVM\_RESUMED_ to primary
+    c. Send *CHECKPOINT_SVM_RESUMED* to primary
 2. Wait a new checkpoint
-    a. Read _CHECKPOINT\_NEW_ from primary
+    a. Read *CHECKPOINT_NEW* from primary
 3. Suspend secondary vm
     a. Suspend secondary vm
-    b. Send _CHECKPOINT\_SVM\_SUSPENDED_ to primary
+    b. Send *CHECKPOINT_SVM_SUSPENDED* to primary
 4. Checkpoint
 
 Future Extensions