diff --git a/build.sh b/build.sh index 698283b..2b01c78 100755 --- a/build.sh +++ b/build.sh @@ -490,21 +490,61 @@ do_md_fixups() { # TODO: Turn this into a Pandoc filter. sed -i.bak '0,/\\tableofcontents/s/^# \(.*\)/\\section*\{\U\1\}/g' "${input}" } -do_tex_fixups() { + +# latexdiff is pretty great, but it has some incompatibilities with our template, so we +# unfortunately have to do a lot of massaging of the diff .tex file here. +# In the future, we should explore whether latexdiff can be further configured, our +# our custom extensions can be redesigned to avoid some of these problems. +do_diff_tex_fixups() { local input=$1 # latexdiff is appending its own generated preamble to our custom one # (in apparent contradiction of the documentation). Strip it out. sed -i.bak '/^% End Custom TCG/,/^%DIF END PREAMBLE EXTENSION/d' "${input}" # latexdiff uses %DIF < and %DIF > to prefix changed lines in code environments - # prefix these lines with + and - - sed -i.bak 's/^%DIF < /%DIF <- /g' "${input}" - sed -i.bak 's/^%DIF > /%DIF >+ /g' "${input}" - - # latexdiff' \DIFaddbegin absorbs a space before it. - # This is fairly common (e.g., in the case of an added sentence) - # Preserve them by inserting a space after. - sed -i.bak 's/ \\DIFaddbegin/ \\DIFaddbegin ~/g' "${input}" + # prefix these lines with + and - and replace %DIF with DIFDIFDIFDIF (inside DIFverbatim) so that + # we don't delete the verbatim diff markers when we delete comments below. + sed -i.bak '/\\begin{DIFverbatim}/,/\\end{DIFverbatim}/s/^%DIF < /DIFDIFDIFDIF <- /g' "${input}" + sed -i.bak '/\\begin{DIFverbatim}/,/\\end{DIFverbatim}/s/^%DIF > /DIFDIFDIFDIF >+ /g' "${input}" + + # Remove all block begin and end markers after the beginning of the document. See latexdiff.tex for some discussion on this. + # TL;DR: the begin and end markers get put into tricky places, and we don't need to do anything inside those commands. + sed -i.bak '/^\\begin{document}/,$s/\\DIF\(add\|del\|mod\)\(begin\|end\)\(FL\|\) //g ' "${input}" + + # latexdiff erroneously puts \DIFadd inside the second argument to \multicolumn. + # Move it out. + sed -i.bak 's/\\multicolumn{\([^{}]*\)}{\\DIFadd{\([^{}]*\|[^{}]*{[^{}]*}\)}}/\\multicolumn{\1}{\2}/g' "${input}" + + # Delete all lines containing only comments. + sed -i.bak '/^\s*%.*$/d' "${input}" + + # Strip comments (everything after unescaped percent signs) inside of xltabular to make the below steps easier. + sed -i.bak '/\\begin{xltabular}/,/\\end{xltabular}/s/\([^\\]\)%.*$/\1/g' "${input}" + sed -i.bak 's/^%.*$//g' "${input}" + + # Combine lines inside of the xltabular environment so that (non-empty) lines all end in \\ or \\* + perl -ne 's/\n/ / if $s = /\\begin{xltabular}/ .. ($e = /\\end{xltabular}/) + and $s > 1 and !$e and !/.*\\\\$/ and !/.*\\\\\*$/; + print' < "${input}" > "${input}".bak && mv "${input}".bak "${input}" + + # Put newlines after \endhead, \endfirsthead, \endfoot, and \endlastfoot + sed -i.bak 's/\(\\end\(head\|firsthead\|foot\|lastfoot\)\)/\1\n/g' "${input}" + + # latexdiff inserts its markers before \multicolumn sometimes. + # The \multicolumn needs to be the first thing in the cell. + # Swap the order of any \DIF stuff and \multicolumn invocation inside a cell. + sed -i.bak 's/\(\\DIF[^&]*\)\(\\multicolumn{[^{}]*}\({[^{}]*}\|{[^{}]*{[^{}]*}}\)\)/\2\1/g' "${input}" + + # latexdiff inserts its markers before \hline sometimes. + # After the transformations above, \hline needs to be the first thing in a line of text. + sed -i.bak 's/\(\s*\)\(.*\)\(\\hline \|\\hlineifmdframed \)\(.*\)/\1\3\2\4/g' "${input}" + + # latexdiff inside of \texttt breaks. Prefer \ttfamily. + sed -i.bak 's/\\texttt{/{\\ttfamily /g' "${input}" + + # Delete all empty DIFadd/mod/del + sed -i.bak 's/\\DIF\(add\|del\|mod\){}\(FL\|\)//g' "${input}" + } if test "${DO_GITVERSION}" == "yes"; then @@ -819,7 +859,7 @@ if [ -n "${DIFFPDF_OUTPUT}" -o -n "${DIFFTEX_OUTPUT}" ]; then do_latex "${BUILD_DIR}/${INPUT_FILE}" "${TEMP_DIFFBASE_TEX_FILE}" "${EXTRA_PANDOC_OPTIONS} -V keepstaleimages=true" echo "Running latexdiff... (this may take a while for complex changes)" start=$(date +%s) - latexdiff-fast --preamble /resources/templates/latexdiff.tex --config /resources/templates/latexdiff.cfg --append-safecmd /resources/templates/latexdiff.safe --exclude-safecmd /resources/templates/latexdiff.unsafe "${TEMP_DIFFBASE_TEX_FILE}" "${TEMP_TEX_FILE}" > "${TEMP_DIFF_TEX_FILE}" 2>"${TEMP_LATEXDIFF_LOG}" + latexdiff-fast --math-markup=whole --preamble /resources/templates/latexdiff.tex --config /resources/templates/latexdiff.cfg --append-safecmd /resources/templates/latexdiff.safe --exclude-safecmd /resources/templates/latexdiff.unsafe "${TEMP_DIFFBASE_TEX_FILE}" "${TEMP_TEX_FILE}" > "${TEMP_DIFF_TEX_FILE}" 2>"${TEMP_LATEXDIFF_LOG}" end=$(date +%s) echo "Elapsed time: $(($end-$start)) seconds" if [ $? -ne 0 ]; then @@ -827,7 +867,7 @@ if [ -n "${DIFFPDF_OUTPUT}" -o -n "${DIFFTEX_OUTPUT}" ]; then >&2 cat "${TEMP_LATEXDIFF_LOG}" echo "latexdiff failed" else - do_tex_fixups "${TEMP_DIFF_TEX_FILE}" + do_diff_tex_fixups "${TEMP_DIFF_TEX_FILE}" if [ -n "${DIFFTEX_OUTPUT}" ]; then mkdir -p "$(dirname ${SOURCE_DIR}/${DIFFTEX_OUTPUT})" cp "${TEMP_DIFF_TEX_FILE}" "${SOURCE_DIR}/${DIFFTEX_OUTPUT}" diff --git a/guide.tcg b/guide.tcg index 730669a..706bd13 100644 --- a/guide.tcg +++ b/guide.tcg @@ -93,66 +93,69 @@ A typical GitHub Markdown repo will: * Cache the LaTex intermediate files to the GitHub actions cache. This allows small changes to the doc to render faster. -`.github/workflows/actions.yml` might look a bit like this: +The recommended way to do this is to use the +[reusable GitHub workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows) +in +[trustedcomputinggroup/pandoc](https://github.com/trustedcomputinggroup/pandoc)'s +.github/workflows directory. + +Another project's `.github/workflows/render.yml` might look a bit like this: ```yaml -name: Render spec +name: Render + on: - pull_request: - release: - types: [published] + workflow_call: + inputs: + workflow: + description: the workflow to run ('pr', 'push', 'release', 'manual') + required: true + type: string + revision: + description: version to render (default is default branch) + required: false + type: string + manual_diffbase: + description: diffbase for manual workflow + required: false + type: string jobs: render: - runs-on: ubuntu-latest - container: - image: ghcr.io/trustedcomputinggroup/pandoc:0.9.10 - name: Render PDF and Word - steps: - - name: Checkout - uses: actions/checkout@v3 - with: - fetch-depth: 0 - fetch-tags: true + uses: trustedcomputinggroup/pandoc/.github/workflows/render.yml@v0.15.4 + with: + container-version: 0.15.4 + input: spec.tcg + workflow: ${{ inputs.workflow }} + revision: ${{ inputs.revision }} + manual_diffbase: ${{ inputs.manual_diffbase }} +``` - - name: Cache LaTeX files - uses: actions/cache@v3 - env: - cache-name: cache-latex-files - with: - path: | - *.aux - *.fdb_latexmk - *.lof - *.lot - *.toc - key: latex-${{ github.run_id }} - restore-keys: latex - - - name: Render - uses: trustedcomputinggroup/markdown@v0.4.2 - with: - input-md: spec.md - output-pdf: spec.pdf - output-docx: spec.docx +The reusable workflows provided by this repository support four different operations: - - name: Upload PDF to PR - uses: actions/upload-artifact@master - if: ${{ github.event_name == 'pull_request' }} - with: - name: spec.pdf - path: spec.pdf +Table: Reusable Workflow Operations {#tbl:reusable-workflows} - - name: Upload PDF and docx to release - uses: svenstaro/upload-release-action@v2 - if: ${{ github.event_name == 'release' }} - with: - repo_token: ${{ secrets.GITHUB_TOKEN }} - file: spec.* - tag: ${{ github.ref }} - overwrite: true - file_glob: true -``` ++----------------------+----------------------------+ +| Workflow | Description | ++======================+============================+ +| pr | Render the spec and diff | +| | the change in the PR, | +| | attaching both to the | +| | "Artifacts" tab of the PR. | ++----------------------+----------------------------+ +| push | Render the spec and attach | +| | it to the action's | +| | "Artifacts" tab. | ++----------------------+----------------------------+ +| release | Render the spec and attach | +| | it to the release. | ++----------------------+----------------------------+ +| manual | (Triggered manually) | +| | Render the spec at the | +| | revision `revision` with | +| | optional diffing to | +| | `manual_diffbase`. | ++----------------------+----------------------------+ ## Local Testing @@ -863,38 +866,48 @@ Table: Fruits (Grid) {#tbl:fruits-grid} +-------------+--------+----------------------------+ A grid table can be divided into sections using `===` in a full-span row, -as in @tbl:some-command: +as in @tbl:subsections: ```md -Table: Some Command {#tbl:some-command} +Table: Complex Table With Subsections {#tbl:subsections} +-------------+--------+----------------------------+ -| Type | Name | Description | +| Fruit | Color | Description | +=============+========+============================+ -| ================= Header ======================== | +| =============== Tree Fruits ===================== | ++-------------+--------+----------------------------+ +| Apple | Red | Useful for pie. | ++-------------+--------+----------------------------+ +| Pear | Green | Useful for pie? | +-------------+--------+----------------------------+ -| UINT32 | Siz | The size of the following | -| | | contents. | +| ================= Berries ======================= | +-------------+--------+----------------------------+ -| ================ Contents ======================= | +| Cherry | Red | Useful for pie. | +-------------+--------+----------------------------+ -| BYTE\[Siz\] | Items | `Size` many items. | +| Banana | Yellow | Useful for pie. | ++-------------+--------+----------------------------+ +| Tomato | Red | Not useful for pie. | +-------------+--------+----------------------------+ ``` -Table: Some Command {#tbl:some-command} +Table: Complex Table With Subsections {#tbl:subsections} +-------------+--------+----------------------------+ -| Type | Name | Description | +| Fruit | Color | Description | +=============+========+============================+ -| ================= Header ======================== | +| =============== Tree Fruits ===================== | ++-------------+--------+----------------------------+ +| Apple | Red | Useful for pie. | ++-------------+--------+----------------------------+ +| Pear | Green | Useful for pie? | ++-------------+--------+----------------------------+ +| ================= Berries ======================= | +-------------+--------+----------------------------+ -| UINT32 | Siz | The size of the following | -| | | contents. | +| Cherry | Red | Useful for pie. | +-------------+--------+----------------------------+ -| ================ Contents ======================= | +| Banana | Yellow | Useful for pie. | +-------------+--------+----------------------------+ -| BYTE\[Siz\] | Items | `Siz` many items. | +| Tomato | Red | Not useful for pie. | +-------------+--------+----------------------------+ * The row must span the entire table @@ -904,16 +917,21 @@ Table: Some Command {#tbl:some-command} Below is a table with full-span rows that do not use this feature: +-------------+--------+----------------------------+ -| Type | Name | Description | +| Fruit | Color | Description | +=============+========+============================+ -| Header | +| Tree Fruits | +-------------+--------+----------------------------+ -| UINT32 | Siz | The size of the following | -| | | contents. | +| Apple | Red | Useful for pie. | +-------------+--------+----------------------------+ -| Contents | +| Pear | Green | Useful for pie? | +-------------+--------+----------------------------+ -| BYTE\[Siz\] | Items | `Siz` many items. | +| Berries | ++-------------+--------+----------------------------+ +| Cherry | Red | Useful for pie. | ++-------------+--------+----------------------------+ +| Banana | Yellow | Useful for pie. | ++-------------+--------+----------------------------+ +| Tomato | Red | Not useful for pie. | +-------------+--------+----------------------------+ ### Styling Markdown Tables @@ -1818,129 +1836,6 @@ Table: Caption but Not Listed {#tbl:no-entry-grid .unnumbered .unlisted} --- -## Something - -Something something something, need to get the spacing on the table just right -to reproduce a possible issue with page breaks, something something something -something something something something something something something something -something something something something something. - -
Capability Name | -Value | -Comments | -
---|---|---|
TPM_PT_PCR_FIRST | -0x00000000 | -bottom of the range of TPM_PT_PCR properties | -
TPM_PT_PCR_SAVE | -0x00000000 | -a SET bit in the TPMS_PCR_SELECT indicates that the PCR is saved and -restored by TPM_SU_STATE | -
TPM_PT_PCR_EXTEND_L0 | -0x00000001 | -a SET bit in the TPMS_PCR_SELECT indicates that the PCR may be -extended from locality 0 -This property is only present if a locality other than 0 is -implemented. |
-
TPM_PT_PCR_RESET_L0 | -0x00000002 | -a SET bit in the TPMS_PCR_SELECT indicates that the PCR may be reset -by TPM2_PCR_Reset() from locality 0 | -
TPM_PT_PCR_EXTEND_L1 | -0x00000003 | -a SET bit in the TPMS_PCR_SELECT indicates that the PCR may be -extended from locality 1 -This property is only present if locality 1 is implemented. |
-
TPM_PT_PCR_RESET_L1 | -0x00000004 | -a SET bit in the TPMS_PCR_SELECT indicates that the PCR may be -reset by TPM2_PCR_Reset() from locality 1 -This property is only present if locality 1 is implemented. |
-
TPM_PT_PCR_EXTEND_L2 | -0x00000005 | -a SET bit in the TPMS_PCR_SELECT indicates that the PCR may be -extended from locality 2 -This property is only present if localities 1 and 2 are -implemented. |
-
TPM_PT_PCR_RESET_L2 | -0x00000006 | -a SET bit in the TPMS_PCR_SELECT indicates that the PCR may be -reset by TPM2_PCR_Reset() from locality 2 -This property is only present if localities 1 and 2 are -implemented. |
-
TPM_PT_PCR_EXTEND_L3 | -0x00000007 | -a SET bit in the TPMS_PCR_SELECT indicates that the PCR may be -extended from locality 3 -This property is only present if localities 1, 2, and 3 are -implemented. |
-
TPM_PT_PCR_RESET_L3 | -0x00000008 | -a SET bit in the TPMS_PCR_SELECT indicates that the PCR may be -reset by TPM2_PCR_Reset() from locality 3 -This property is only present if localities 1, 2, and 3 are -implemented. |
-
TPM_PT_PCR_EXTEND_L4 | -0x00000009 | -a SET bit in the TPMS_PCR_SELECT indicates that the PCR may be -extended from locality 4 -This property is only present if localities 1, 2, 3, and 4 are -implemented. |
-
TPM_PT_PCR_RESET_L4 | -0x0000000A | -a SET bit in the TPMS_PCR_SELECT indicates that the PCR may be -reset by TPM2_PCR_Reset() from locality 4 -This property is only present if localities 1, 2, 3, and 4 are -implemented. |
-
reserved | -0x0000000B - 0x00000010 | -the values in this range are reserved -They correspond to values that may be used to describe attributes -associated with the extended localities (32-255).synthesize additional -software localities. The meaning of these properties need not be the -same as the meaning for the Extend and Reset properties above. |
-