Fix crossrefs for metadata spec, deduplicate conf and macros

Author: yuri91

document/core/appendix/custom.rst

@@ -239,63 +239,6 @@ It may only be placed on a declaration that declares exactly one local.
    \end{array}
 
 
-.. index:: ! branch hints section, hint
-.. _binary-branchhintsec:
-
-Branch Hint Section
-~~~~~~~~~~~~~~~~~~~~
-
-The *branch hint section* is a :ref:`custom section <binary-customsec>` whose name string is :math:`\text{metadata.code.branch\_hint}`.
-The branch hints section should appear only once in a module, and only before the :ref:`code section <binary-codesec>`.
-
-The purpose of this section is to aid the compilation of conditional branch instructions, by providing a hint that a branch is very likely (or unlikely) to be taken.
-
-The section contains a vector of *function branch hints* each representing the branch hints for a single function.
-
-Each *function branch hints* structure consists of
-
-* the :ref:`function index <binary-funcidx>` of the function the hints are referring to,
-* a vector of *branch hint* for the function.
-
-Elements of the vector of *function branch hints* must appear in increasing function index order,
-and a function index can appear at most once.
-
-Each *branch hint* structure consists of
-
-* the |U32| byte offset of the hinted instruction from the beginning of the function body,
-* A |U32| with value '1',
-* a |U32| indicating the meaning of the hint:
-
-=====  ===========================================
-Value  Meaning                                    
-=====  ===========================================
- 0x00  branch likely not taken
- 0x01  branch likely taken
-=====  ===========================================
-
-Elements of the vector of *branch hint* must appear in increasing byte offset order,
-and a byte offset can appear at most once. A |BRIF| or |IF| instruction must be present
-in the code section at the specified offset.
-
-.. math::
-   \begin{array}{llcll}
-   \production{branch hint section} & \Bbranchhintsec &::=&
-     \Bsection_0(\Bbranchhintdata) \\
-   \production{branch hint data} & \Bbranchhintdata &::=&
-     n{:}\Bname & (\iff n = \text{metadata.code.branch\_hint}) \\ &&&
-     \Bvec(\Bfuncbranchhints) \\
-   \production{function branch hints} & \Bfuncbranchhints &::=&
-     fidx{:}\Bfuncidx~\Bvec(\Bbranchhint) \\
-   \production{branch hint} & \Bbranchhint &::=&
-     \X{instoff}{:}\Bu32 ~~ 1{:}\Bu32 ~~ \Bbranchhintkind \\
-   \production{branch hint kind} & \Bbranchhintkind &::=&
-     \hex{00} \\ &&|&
-     \hex{01} \\
-   \end{array}
-.. index:: ! custom annotation, custom section
-.. _text-customannot:
-
-
 Custom Annotations
 ~~~~~~~~~~~~~~~~~~
 
@@ -394,26 +337,3 @@ Their relative placement will depend on the placement directive given for the :m
       custom section "A"
       custom section "D"
 
-
-.. index:: ! branch hints annotation, hint
-.. _text-branchhintannot:
-
-Branch Hint Annotations
-~~~~~~~~~~~~~~~~~~~~~~~
-
-*Branch Hint annotations* are the textual analogue to the :ref:`branch hint section <binary-branchhintsec>` and provide a textual representation for it.
-Consequently, their id is :math:`\T{@metadata.code.branch\_hint}`.
-
-Branch hint annotations are allowed only on |BRIF| and |IF| instructions,
-and at most one branch hint annotation may be given per instruction.
-
-Branch hint annotations have the following format:
-
-.. math::
-   \begin{array}{llclll}
-   \production{branch hint annotation} & \Tbranchhintannot &::=&
-     \text{(@metadata.code.branch\_hint}~\Tbranchhintstr~\text{)} \\
-   \production{branch hint string} & \Tbranchhintstr &::=&
-     \text{"\backslash 00"} \\ &&|&
-     \text{"\backslash 01"} \\
-   \end{array}

document/core/util/macros.def

@@ -1271,14 +1271,6 @@
 .. |Bfuncnamesubsec| mathdef:: \xref{appendix/custom}{binary-funcnamesec}{\B{funcnamesubsec}}
 .. |Blocalnamesubsec| mathdef:: \xref{appendix/custom}{binary-localnamesec}{\B{localnamesubsec}}
 
-.. Branch Hints Section, non-terminals
-
-.. |Bbranchhintsec| mathdef:: \xref{appendix/custom}{binary-branchhintsec}{\B{branchhintsec}}
-.. |Bbranchhintdata| mathdef:: \xref{appendix/custom}{binary-branchhintsec}{\B{branchhintdata}}
-.. |Bfuncbranchhints| mathdef:: \xref{appendix/custom}{binary-branchhintssec}{\B{funcbranchhints}}
-.. |Bbranchhint| mathdef:: \xref{appendix/custom}{binary-branchhintsec}{\B{branchhint}}
-.. |Bbranchhintkind| mathdef:: \xref{appendix/custom}{binary-branchhintsec}{\B{branchhintkind}}
-
 .. Annotations
 .. -----------
 
@@ -1297,11 +1289,6 @@
 .. |Tparamnameannot| mathdef:: \xref{appendix/custom}{text-paramnameannot}{\T{paramnameannot}}
 .. |Tlocalnameannot| mathdef:: \xref{appendix/custom}{text-localnameannot}{\T{localnameannot}}
 
-.. Branch Hint annotations, non-terminals
-
-.. |Tbranchhintannot| mathdef:: \xref{appendix/custom}{text-branchhintannot}{\T{branchhintannot}}
-.. |Tbranchhintstr| mathdef:: \xref{appendix/custom}{text-branchhintannot}{\T{branchhintstr}}
-
 
 .. Embedding
 .. ---------

document/metadata/code/binary.rst

@@ -3,6 +3,8 @@
 Binary Format
 =============
 
+.. _binary-codemetadata:
+
 Code Metadata
 -------------
 
@@ -30,6 +32,8 @@ Where *funcpos* is the byte offset of the annotation starting from the beginning
 
 *code metadata function* entries must appear in order of increasing *function id*, and duplicate id values are not allowed. *code metadata item* entries must appear in order of increasing *instruction offset*, and duplicate offset values are not allowed.
 
+.. _binary-branchhints:
+
 Branch Hints
 ~~~~~~~~~~~~
 

document/metadata/code/conf.py

@@ -19,6 +19,8 @@
 import sys
 from datetime import date
 
+core_dir = os.path.abspath('../../core')
+sys.path.insert(0, core_dir)
 pwd = os.path.abspath('.')
 sys.path.insert(0, pwd)
 
@@ -294,7 +296,7 @@
 
    # Additional stuff for the LaTeX preamble.
    # Don't type-set cross references with emphasis.
-   'preamble': '\\renewcommand\\sphinxcrossref[1]{#1}\n',
+   'preamble': '\\renewcommand\\sphinxcrossref[1]{#1}\n\\externaldocument[Core-]{'+core_dir+'/_build/latex/WebAssembly}[https://webassembly.github.io//'+repo+'/core/_download/WebAssembly.pdf]\n',
 
    # Latex figure (float) alignment
   'figure_align': 'htbp',
@@ -303,7 +305,9 @@
    'fncychap': '\\usepackage[Sonny]{fncychap}',
 
    # Allow chapters to start on even pages
-   'extraclassoptions': 'openany'
+   'extraclassoptions': 'openany',
+
+   'extrapackages': '\\usepackage{xr-hyper}',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
@@ -489,6 +493,7 @@
 rst_prolog = """
 .. |issuelink| replace:: https://github.com/webassembly/""" + repo + """/issues/
 .. |pagelink| replace:: https://webassembly.github.io/""" + repo + """/core/
+.. include:: /""" + core_dir + """/util/macros.def
 .. include:: /""" + pwd + """/util/macros.def
 """
 

document/metadata/code/text.rst

@@ -3,6 +3,8 @@
 Text Format
 ===========
 
+.. _text-codemetadata:
+
 Code Metadata
 -------------
 
@@ -15,6 +17,7 @@ attached to the first instruction that follows them.
    \production{code metadata annotation} & \Tcodemetadataannot(\B{T}) &::=&
      \text{(@metadata.code.T}~\X{data}{:}\B{T}~\text{)} \\
    \end{array}
+.. index:: ! code metadata annotation
 
 Where `T` is the type of the item, and `data` is a byte string containing the same
 payload as in the binary format.