From 1a68960fcf4540fcbd4371d175432a899bf64494 Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Wed, 16 Oct 2024 14:13:26 +0000 Subject: [PATCH 1/8] Replace a table (test commit for diffing) --- guide.tcg | 57 ++++++++++++++++++++++++++---------------- template/latexdiff.tex | 27 -------------------- 2 files changed, 36 insertions(+), 48 deletions(-) diff --git a/guide.tcg b/guide.tcg index 730669a..3d27a68 100644 --- a/guide.tcg +++ b/guide.tcg @@ -863,38 +863,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 ===================== | +-------------+--------+----------------------------+ -| UINT32 | Siz | The size of the following | -| | | contents. | +| Apple | Red | Useful for pie. | +-------------+--------+----------------------------+ -| ================ Contents ======================= | +| Pear | Green | Useful for pie? | +-------------+--------+----------------------------+ -| BYTE\[Siz\] | Items | `Size` many items. | +| ================= Berries ======================= | ++-------------+--------+----------------------------+ +| Cherry | Red | Useful for pie. | ++-------------+--------+----------------------------+ +| 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? | +-------------+--------+----------------------------+ -| UINT32 | Siz | The size of the following | -| | | contents. | +| ================= Berries ======================= | +-------------+--------+----------------------------+ -| ================ Contents ======================= | +| Cherry | Red | Useful for pie. | +-------------+--------+----------------------------+ -| BYTE\[Siz\] | Items | `Siz` many items. | +| Banana | Yellow | Useful for pie. | ++-------------+--------+----------------------------+ +| Tomato | Red | Not useful for pie. | +-------------+--------+----------------------------+ * The row must span the entire table @@ -904,16 +914,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 | ++-------------+--------+----------------------------+ +| 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. | +-------------+--------+----------------------------+ ### Styling Markdown Tables diff --git a/template/latexdiff.tex b/template/latexdiff.tex index 3f06f94..d23637d 100644 --- a/template/latexdiff.tex +++ b/template/latexdiff.tex @@ -29,33 +29,6 @@ \providecommand{\DIFdelbeginFL}{\pdfmargincomment[author=DIFF,icon=Note,color=tcg-template-neon-green]{Removed image}} \providecommand{\DIFdelendFL}{} -% % Latexdiff by default wants to shrink deleted figures. Let's try not doing that, -% % but if we want to change this later, here's what was here once. -% \newcommand{\DIFscaledelfig}{1.0} -% \RequirePackage{settobox} -% \RequirePackage{letltxmacro} -% \newsavebox{\DIFdelgraphicsbox} -% \newlength{\DIFdelgraphicswidth} -% \newlength{\DIFdelgraphicsheight} -% % store original definition of \includegraphics %DIF PREAMBLE -% \LetLtxMacro{\DIFOincludegraphics}{\includegraphics} %DIF PREAMBLE -% \newcommand{\DIFaddincludegraphics}[2][]{{\color{blue}\fbox{\DIFOincludegraphics[#1]{#2}}}} %DIF PREAMBLE -% \newcommand{\DIFdelincludegraphics}[2][]{% %DIF PREAMBLE -% \sbox{\DIFdelgraphicsbox}{\DIFOincludegraphics[#1]{#2}}% %DIF PREAMBLE -% \settoboxwidth{\DIFdelgraphicswidth}{\DIFdelgraphicsbox} %DIF PREAMBLE -% \settoboxtotalheight{\DIFdelgraphicsheight}{\DIFdelgraphicsbox} %DIF PREAMBLE -% \scalebox{\DIFscaledelfig}{% %DIF PREAMBLE -% \parbox[b]{\DIFdelgraphicswidth}{\usebox{\DIFdelgraphicsbox}\\[-\baselineskip] \rule{\DIFdelgraphicswidth}{0em}}\llap{\resizebox{\DIFdelgraphicswidth}{\DIFdelgraphicsheight}{% %DIF PREAMBLE -% \setlength{\unitlength}{\DIFdelgraphicswidth}% %DIF PREAMBLE -% \begin{picture}(1,1)% %DIF PREAMBLE -% \thicklines\linethickness{2pt} %DIF PREAMBLE -% {\color[rgb]{1,0,0}\put(0,0){\framebox(1,1){}}}% %DIF PREAMBLE -% {\color[rgb]{1,0,0}\put(0,0){\line( 1,1){1}}}% %DIF PREAMBLE -% {\color[rgb]{1,0,0}\put(0,1){\line(1,-1){1}}}% %DIF PREAMBLE -% \end{picture}% %DIF PREAMBLE -% }\hspace*{3pt}}} %DIF PREAMBLE -% } %DIF PREAMBLE - % Add a PDF comment and put a box around the added and removed graphics. % store original definition of \includegraphics so we can wrap it. \LetLtxMacro{\DIFOincludegraphics}{\includegraphics} From d01e1651e9081fd75d758790ea61b008d6cc2390 Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Wed, 16 Oct 2024 14:14:06 +0000 Subject: [PATCH 2/8] Delete a table (test commit for diffing) --- guide.tcg | 123 ------------------------------------------------------ 1 file changed, 123 deletions(-) diff --git a/guide.tcg b/guide.tcg index 3d27a68..8bb3395 100644 --- a/guide.tcg +++ b/guide.tcg @@ -1833,129 +1833,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. - - - ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Definition of -(UINT32) `TPM_PT_PCR` Constants -
Capability NameValueComments
TPM_PT_PCR_FIRST0x00000000bottom of the range of TPM_PT_PCR properties
TPM_PT_PCR_SAVE0x00000000a SET bit in the TPMS_PCR_SELECT indicates that the PCR is saved and -restored by TPM_SU_STATE
TPM_PT_PCR_EXTEND_L00x00000001

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_L00x00000002a 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_L10x00000003

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_L10x00000004

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_L20x00000005

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_L20x00000006

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_L30x00000007

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_L30x00000008

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_L40x00000009

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_L40x0000000A

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.

reserved0x0000000B - 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.

- Verify that the table cross-references still work: * @tbl:bullets-grid From 97618a8d569c0b979c1e2bed5b2230c74c1d1b28 Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Wed, 16 Oct 2024 14:24:01 +0000 Subject: [PATCH 3/8] Add a table (test commit for diffing) --- guide.tcg | 105 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 54 insertions(+), 51 deletions(-) diff --git a/guide.tcg b/guide.tcg index 8bb3395..27b94c1 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/actions.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 From 06e3e9ef2f8ebb45c91b7cbe28faae3f7a099491 Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Wed, 16 Oct 2024 15:24:03 +0000 Subject: [PATCH 4/8] add some sed hacks to fix some table diffs --- build.sh | 8 +++++++- guide.tcg | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/build.sh b/build.sh index 698283b..3e26f32 100755 --- a/build.sh +++ b/build.sh @@ -501,10 +501,16 @@ do_tex_fixups() { sed -i.bak 's/^%DIF < /%DIF <- /g' "${input}" sed -i.bak 's/^%DIF > /%DIF >+ /g' "${input}" - # latexdiff' \DIFaddbegin absorbs a space before it. + # latexdiff's \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}" + + # latexdiff erroneously puts \DIFadd inside the second argument to \multicolumn. + sed -i.bak 's/\\multicolumn{\([^}]*\)}{\\DIFadd{\([^}]*\)}}/\\multicolumn{\1}{\2}/g' "${input}" + + # latexdiff puts \DIFaddend at the beginning of a table row instead of the end of the previous row + sed -z -i.bak 's/ \\\\\n\n\\hline\s*\\DIFaddend/\\DIFaddend \\\\\n\n\\hline/g' "${input}" } if test "${DO_GITVERSION}" == "yes"; then diff --git a/guide.tcg b/guide.tcg index 27b94c1..706bd13 100644 --- a/guide.tcg +++ b/guide.tcg @@ -99,7 +99,7 @@ in [trustedcomputinggroup/pandoc](https://github.com/trustedcomputinggroup/pandoc)'s .github/workflows directory. -Another project's `.github/workflows/actions.yml` might look a bit like this: +Another project's `.github/workflows/render.yml` might look a bit like this: ```yaml name: Render From dd9720db78e62146b5464b5f3c40e0980faf62df Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Wed, 16 Oct 2024 22:03:55 +0000 Subject: [PATCH 5/8] Perform fixups that get Part 1 happy --- build.sh | 39 ++++++++++++++++++++++++++++++++++----- template/latexdiff.unsafe | 1 + 2 files changed, 35 insertions(+), 5 deletions(-) diff --git a/build.sh b/build.sh index 3e26f32..b75dd09 100755 --- a/build.sh +++ b/build.sh @@ -501,16 +501,45 @@ do_tex_fixups() { sed -i.bak 's/^%DIF < /%DIF <- /g' "${input}" sed -i.bak 's/^%DIF > /%DIF >+ /g' "${input}" + # latexdiff erroneously puts \DIFadd inside the second argument to \multicolumn. + sed -i.bak 's/\\multicolumn{\([^{}]*\)}{\\DIFadd{\([^{}]*\|[^{}]*{[^{}]*}\)}}/\\multicolumn{\1}{\2}/g' "${input}" + + # latexdiff erroneously puts \DIFaddend inside the second argument to \multicolumn. + sed -i.bak 's/\\multicolumn{\([^{}]*\)}{\\DIFaddend \([^{}]*\|[^{}]*{[^{}]*}\)}/\\multicolumn{\1}{\2} \\DIFaddend/g' "${input}" + + # latexdiff puts \DIFaddend at the beginning of a table row instead of the end of the previous row. + sed -z -i.bak 's/ \\\\\n\n\\hline\s*\\DIFaddend/\\DIFaddend \\\\\n\n\\hline/g' "${input}" + + # Remove \DIFaddbegin that contain nothing but a \multicolumn spec. + # This is inserted if the number of columns was detected to change. + # diff markers will be inserted in the actual new contents, so we don't + # need these ones. + sed -i.bak 's/\\DIFaddbegin\s*\(\\multicolumn{[^{}]*}\({[^{}]*}\|{[^{}]*{[^{}]*}}\)\)\s*\\DIFaddend/\1/g' "${input}" + + # Strip comments (everything after unescaped percent signs) to make the below steps easier. + sed -i.bak '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}" + + # Remove \DIFdelbegin that contain nothing. + sed -i.bak 's/\\DIFdelbegin\s*\\DIFdelend//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's \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}" - # latexdiff erroneously puts \DIFadd inside the second argument to \multicolumn. - sed -i.bak 's/\\multicolumn{\([^}]*\)}{\\DIFadd{\([^}]*\)}}/\\multicolumn{\1}{\2}/g' "${input}" - - # latexdiff puts \DIFaddend at the beginning of a table row instead of the end of the previous row - sed -z -i.bak 's/ \\\\\n\n\\hline\s*\\DIFaddend/\\DIFaddend \\\\\n\n\\hline/g' "${input}" + # latexdiff inside of \texttt breaks. Prefer \ttfamily. + sed -i.bak 's/\\texttt{/{\\ttfamily /g' "${input}" } if test "${DO_GITVERSION}" == "yes"; then diff --git a/template/latexdiff.unsafe b/template/latexdiff.unsafe index 905b651..19958e8 100644 --- a/template/latexdiff.unsafe +++ b/template/latexdiff.unsafe @@ -1 +1,2 @@ label +texttt From 96ac72e0e9df7457c21f23fc4a0ce1b5f0c57fbc Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Wed, 23 Oct 2024 15:13:17 +0000 Subject: [PATCH 6/8] Perform just enough fixups to make TPM spec diffs work --- build.sh | 28 +++++++++------------------- template/latexdiff.tex | 22 ++++++++++++++++------ 2 files changed, 25 insertions(+), 25 deletions(-) diff --git a/build.sh b/build.sh index b75dd09..b511c45 100755 --- a/build.sh +++ b/build.sh @@ -501,20 +501,14 @@ do_tex_fixups() { sed -i.bak 's/^%DIF < /%DIF <- /g' "${input}" sed -i.bak 's/^%DIF > /%DIF >+ /g' "${input}" + # Remove all block begin and end markers after the beginning of the document. See latexdiff.tex for some discussion on this. + 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. sed -i.bak 's/\\multicolumn{\([^{}]*\)}{\\DIFadd{\([^{}]*\|[^{}]*{[^{}]*}\)}}/\\multicolumn{\1}{\2}/g' "${input}" - # latexdiff erroneously puts \DIFaddend inside the second argument to \multicolumn. - sed -i.bak 's/\\multicolumn{\([^{}]*\)}{\\DIFaddend \([^{}]*\|[^{}]*{[^{}]*}\)}/\\multicolumn{\1}{\2} \\DIFaddend/g' "${input}" - - # latexdiff puts \DIFaddend at the beginning of a table row instead of the end of the previous row. - sed -z -i.bak 's/ \\\\\n\n\\hline\s*\\DIFaddend/\\DIFaddend \\\\\n\n\\hline/g' "${input}" - - # Remove \DIFaddbegin that contain nothing but a \multicolumn spec. - # This is inserted if the number of columns was detected to change. - # diff markers will be inserted in the actual new contents, so we don't - # need these ones. - sed -i.bak 's/\\DIFaddbegin\s*\(\\multicolumn{[^{}]*}\({[^{}]*}\|{[^{}]*{[^{}]*}}\)\)\s*\\DIFaddend/\1/g' "${input}" + # Delete all lines containing only comments. + sed -i.bak '/^%.*$/d' "${input}" # Strip comments (everything after unescaped percent signs) to make the below steps easier. sed -i.bak 's/\([^\\]\)%.*$/\1/g' "${input}" @@ -525,18 +519,14 @@ do_tex_fixups() { and $s > 1 and !$e and !/.*\\\\$/ and !/.*\\\\\*$/; print' < "${input}" > "${input}".bak && mv "${input}".bak "${input}" - # Remove \DIFdelbegin that contain nothing. - sed -i.bak 's/\\DIFdelbegin\s*\\DIFdelend//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's \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}" + + # 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}" diff --git a/template/latexdiff.tex b/template/latexdiff.tex index d23637d..df9ae3d 100644 --- a/template/latexdiff.tex +++ b/template/latexdiff.tex @@ -10,13 +10,23 @@ % https://tex.stackexchange.com/questions/474947/highlighting-text-that-spans-multiple-lines-with-pdfmarkupcomment-from-pdfcomme % \providecommand{\DIFadd}[1]{\pdfmarkupcomment[author=Inserted,markup=Underline,color=blue]{#1}{#1}} % \providecommand{\DIFdel}[1]{\pdfmarkupcomment[author=Deleted,markup=StrikeOut,color=red]{#1}{#1}} -\providecommand{\DIFadd}[1]{{\color{blue} \uline{#1}}} -\providecommand{\DIFdel}[1]{{\color{red} \sout{#1}}} -% Basic add/del/mod environments. -% \providecommand{\DIFaddbegin}{\pdfmargincomment[author=Inserted,icon=Note,color=blue]{Text}} -\providecommand{\DIFaddbegin}{\pdfmargincomment[author=DIFF,icon=Note,color=tcg-template-neon-green]{Inserted text}} +\providecommand{\DIFadd}[1]{% + \pdfmargincomment[author=DIFF]{Inserted: \detokenize{#1}}% + {\color{blue} \uline{#1}}% +} +\providecommand{\DIFdel}[1]{% + \pdfmargincomment[author=DIFF]{Removed: \detokenize{#1}}% + {\color{red} \sout{#1}}% +} +% \providecommand{\DIFaddbegin}{\pdfmargincomment[author=DIFF,icon=Note,color=tcg-template-neon-green]{Inserted text}} +% \providecommand{\DIFdelbegin}{\pdfmargincomment[author=DIFF,icon=Note,color=tcg-template-neon-green]{Removed text}} + +% latexdiff provides granular diff markers for text \DIF(add|del) as well as "block" markers \DIF(add|del)(begin|end). +% The block markers are unnecessary and tend to get inserted into incorrect places in the LaTex. +% These all need to be stripped out in post-processing (e.g., with sed). +\providecommand{\DIFaddbegin}{} \providecommand{\DIFaddend}{} -\providecommand{\DIFdelbegin}{\pdfmargincomment[author=DIFF,icon=Note,color=tcg-template-neon-green]{Removed text}} +\providecommand{\DIFdelbegin}{} \providecommand{\DIFdelend}{} \providecommand{\DIFmodbegin}{} \providecommand{\DIFmodend}{} From 00c7cd68cf7c8c578f91864ef3b1c43719627020 Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Wed, 23 Oct 2024 21:44:44 +0000 Subject: [PATCH 7/8] put one pdf comment per page --- build.sh | 19 +++++++++++++------ template/latexdiff.tex | 33 +++++++++++++++++++++++++-------- 2 files changed, 38 insertions(+), 14 deletions(-) diff --git a/build.sh b/build.sh index b511c45..9142049 100755 --- a/build.sh +++ b/build.sh @@ -497,9 +497,9 @@ do_tex_fixups() { 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}" + # prefix these lines with + and - and replace %DIF with DIFDIFDIFDIF + sed -i.bak 's/^%DIF < /DIFDIFDIFDIF <- /g' "${input}" + sed -i.bak '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. sed -i.bak '/^\\begin{document}/,$s/\\DIF\(add\|del\|mod\)\(begin\|end\)\(FL\|\) //g ' "${input}" @@ -508,10 +508,10 @@ do_tex_fixups() { sed -i.bak 's/\\multicolumn{\([^{}]*\)}{\\DIFadd{\([^{}]*\|[^{}]*{[^{}]*}\)}}/\\multicolumn{\1}{\2}/g' "${input}" # Delete all lines containing only comments. - sed -i.bak '/^%.*$/d' "${input}" + sed -i.bak '/^\s*%.*$/d' "${input}" - # Strip comments (everything after unescaped percent signs) to make the below steps easier. - sed -i.bak 's/\([^\\]\)%.*$/\1/g' "${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 \\* @@ -519,6 +519,9 @@ do_tex_fixups() { 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. @@ -530,6 +533,10 @@ do_tex_fixups() { # 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 diff --git a/template/latexdiff.tex b/template/latexdiff.tex index df9ae3d..221d174 100644 --- a/template/latexdiff.tex +++ b/template/latexdiff.tex @@ -1,5 +1,22 @@ % Custom preamble based on --type=pdfmargincomment --driver xetex +% Convenience macro for adding at most one PDF comment per page +\newbool{newpage} +\setbool{newpage}{true} +\newcommand{\onceperpage}[1]{% + \ifbool{newpage}{% + \global\setbool{newpage}{false}% + #1% + }{}% +} +% Reset \newpage to true after shipping out each page. +% https://ctan.math.washington.edu/tex-archive/macros/latex-dev/base/ltshipout-code.pdf +\AddToHook {shipout/after} {\global\setbool{newpage}{true}} + +\providecommand{\MarkDiffPage}{% + \onceperpage{\pdfmargincomment[author=DIFF]{Page modified}}% +} + % Mark up added text with a blue underline, and removed text with a red strikethrough. % Choose blue/red instead of green/red for accessibility (red-green colorblindness modes constitute the most common forms). \RequirePackage{pdfcomment} @@ -11,11 +28,11 @@ % \providecommand{\DIFadd}[1]{\pdfmarkupcomment[author=Inserted,markup=Underline,color=blue]{#1}{#1}} % \providecommand{\DIFdel}[1]{\pdfmarkupcomment[author=Deleted,markup=StrikeOut,color=red]{#1}{#1}} \providecommand{\DIFadd}[1]{% - \pdfmargincomment[author=DIFF]{Inserted: \detokenize{#1}}% + \MarkDiffPage% {\color{blue} \uline{#1}}% } \providecommand{\DIFdel}[1]{% - \pdfmargincomment[author=DIFF]{Removed: \detokenize{#1}}% + \MarkDiffPage% {\color{red} \sout{#1}}% } % \providecommand{\DIFaddbegin}{\pdfmargincomment[author=DIFF,icon=Note,color=tcg-template-neon-green]{Inserted text}} @@ -34,9 +51,9 @@ % For floats, we use the graphics macros below. \providecommand{\DIFaddFL}[1]{#1} \providecommand{\DIFdelFL}[1]{#1} -\providecommand{\DIFaddbeginFL}{\pdfmargincomment[author=DIFF,icon=Note,color=tcg-template-neon-green]{Inserted image}} +\providecommand{\DIFaddbeginFL}{\MarkDiffPage} \providecommand{\DIFaddendFL}{} -\providecommand{\DIFdelbeginFL}{\pdfmargincomment[author=DIFF,icon=Note,color=tcg-template-neon-green]{Removed image}} +\providecommand{\DIFdelbeginFL}{\MarkDiffPage} \providecommand{\DIFdelendFL}{} % Add a PDF comment and put a box around the added and removed graphics. @@ -69,8 +86,8 @@ % Use a code-diff style for diffs in code \RequirePackage{listings} \lstdefinelanguage{DIFcode}{ - moredelim=[il][\color{red}]{\%DIF\ <}, - moredelim=[il][\color{blue}]{\%DIF\ >} + moredelim=[il][\color{red}]{DIFDIFDIFDIF\ <}, + moredelim=[il][\color{blue}]{DIFDIFDIFDIF\ >} } \lstdefinestyle{DIFverbatimstyle}{ basicstyle=\linespread{1.0}\small\ttfamily{}, @@ -80,11 +97,11 @@ keepspaces=true } \lstnewenvironment{DIFverbatim}{ - \pdfmargincomment[author=DIFF,color=tcg-template-neon-green,icon=Note]{- Deleted, + Inserted} + \MarkDiffPage \lstset{style=DIFverbatimstyle} }{} \lstnewenvironment{DIFverbatim*}{ - \pdfmargincomment[author=DIFF,color=tcg-template-neon-green,icon=Note]{- Deleted, + Inserted} + \MarkDiffPage \lstset{style=DIFverbatimstyle,showspaces=true} }{} \lstset{extendedchars=\true,inputencoding=utf8} From 794c9df6f98ea4bd07f260aff32bc3308bcb3989 Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Wed, 23 Oct 2024 23:51:35 +0000 Subject: [PATCH 8/8] finish up changes for diffing to support TPM spec --- build.sh | 20 ++++++++++++++------ template/latexdiff.tex | 16 ++++++++-------- 2 files changed, 22 insertions(+), 14 deletions(-) diff --git a/build.sh b/build.sh index 9142049..2b01c78 100755 --- a/build.sh +++ b/build.sh @@ -490,21 +490,29 @@ 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 - and replace %DIF with DIFDIFDIFDIF - sed -i.bak 's/^%DIF < /DIFDIFDIFDIF <- /g' "${input}" - sed -i.bak 's/^%DIF > /DIFDIFDIFDIF >+ /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. @@ -851,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 @@ -859,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/template/latexdiff.tex b/template/latexdiff.tex index 221d174..61f29a3 100644 --- a/template/latexdiff.tex +++ b/template/latexdiff.tex @@ -48,14 +48,6 @@ \providecommand{\DIFmodbegin}{} \providecommand{\DIFmodend}{} -% For floats, we use the graphics macros below. -\providecommand{\DIFaddFL}[1]{#1} -\providecommand{\DIFdelFL}[1]{#1} -\providecommand{\DIFaddbeginFL}{\MarkDiffPage} -\providecommand{\DIFaddendFL}{} -\providecommand{\DIFdelbeginFL}{\MarkDiffPage} -\providecommand{\DIFdelendFL}{} - % Add a PDF comment and put a box around the added and removed graphics. % store original definition of \includegraphics so we can wrap it. \LetLtxMacro{\DIFOincludegraphics}{\includegraphics} @@ -66,6 +58,14 @@ {\color{red}\fbox{\DIFOincludegraphics[#1]{#2}}} } %DIF PREAMBLE +% For floats, we use the graphics macros below. +\providecommand{\DIFaddFL}[1]{\let\includegraphics\DIFaddincludegraphics #1 \let\includegraphics\DIFOincludegraphics} +\providecommand{\DIFdelFL}[1]{\let\includegraphics\DIFdelincludegraphics #1 \let\includegraphics\DIFOincludegraphics} +\providecommand{\DIFaddbeginFL}{\MarkDiffPage} +\providecommand{\DIFaddendFL}{} +\providecommand{\DIFdelbeginFL}{\MarkDiffPage} +\providecommand{\DIFdelendFL}{} + \LetLtxMacro{\DIFOaddbegin}{\DIFaddbegin} %DIF PREAMBLE \LetLtxMacro{\DIFOaddend}{\DIFaddend} %DIF PREAMBLE \LetLtxMacro{\DIFOdelbegin}{\DIFdelbegin} %DIF PREAMBLE