trustedcomputinggroup / pandoc Goto Github PK

From #32:

I agree with @williamcroberts's feedback here; we may be able to delete the markdown repo entirely in favor of a GH action hosted in this repo.

Composite Workflows

IIUC it's a composite workflow others are using to generate the markdown rendering. However, it requires users to setup the docker container. I think if we move to a reusable workflow, we can move all of the setup into a reusable workflow so callers of the workflow don't have to do anything but use it. Additionally we can just use docker_run, no real need for the docker actions as docker run will pull the image.

markdown project

Do we need this? The pandoc project builds out the samples anyways, couldn't we just coalesce them or is the markdown project exist soley to test the action.yml composite workflow? It seems confusing to have so much stuff spread out, i'm not seeing the value in the decomposition.

• DRAFT text is not vertically centered anymore
• Delete the Note/Example environments, they don't work if there's an & inside
• Allow omitting part of the doc from the TOC (e.g., each and every term in a list of terms)
• Linking between sections by heading, but printing the number
• Increase the width of the numbers in the TOC for very long numbers (e.g. 3 digits)
• <sub> doesn't work
• In some cases in the TPM spec, a command's description is missing and there's a weird empty page
• Support appendices A, B, C, ...
• DRAFT text interferes with selecting document text
• Ensure all other text is selectable
• tbl. x instead of Table X; fig. x instead of Figure X; etc

guide.pdf's list of tables starts with Table 3, because there are two unlisted tables that still contributed to the counter.

I tried to improve this with #69, but then it messed up the links.

Currently tables render as borderless with alternating column colors. We should consider changing to a more traditional format which matches existing docs. This also includes how table headers are rendered.

Current rendering

Example desired rendering

From #32:

The PR builds and publishes docker container

a. Requires perms on incoming PRs which should be treated as untrusted even through it's inter-org. Don't trust Bill.
b. PRs race on publishing the image

Proposal: for PRs and pushes, do a docker build and docker run manually. The images for github actions contain all the
docker things, no need to really use the composite actions or reusable workflows for that. Only on push should publish the
container to the registry. Do we really need to publish and check-in the generated files?

We use pdflscape to rotate landscape pages on electronic displays while printing them as expected (i.e., without shrinking or cropping). The TPMWG asked for the .landscape option to rotate the other way. I thought this would be easy, but it is not an existing option of the latex package we are using.

Prior art:

https://tex.stackexchange.com/questions/699688/pdflscape-counterclockwise-landscape-with-section

Pull requests for this would be welcome, but I don't have bandwidth to work on this.

It would be neat to have something like

<!-- Table: some-file.csv -->

and have a checked-in csv file get turned into a table.

Another possibility would be to have a tag on the table in native Markdown that makes the tools automatically generate a CSV file from the contents of the table.

It’s like there is an empty caption being added, which wastes vertical space.

https://github.com/chrisfenner/tpm-spec/blob/46dea6eef24897c0be7a2b04a785c7c53c780baf/part1.md

We should try to make the Word output more similar to the PDF output by supporting landscape orientation pages.

I made a little progress on this, but had to set it aside.

These Pandoc lua elements will manipulate section breaks and page orientations.

local wordStartLandscape = pandoc.RawBlock(
    'openxml',
    '<w:pPr><w:sectPr><w:pgSz w:w="12240" w:h="15840"/></w:sectPr></w:pPr><w:lastRenderedPageBreak/>'
)

local wordEndLandscape = pandoc.RawBlock(
    'openxml',
    '<w:br w:type="page"/><w:pPr><w:sectPr><w:pgSz w:w="15840" w:h="12240" w:orient="landscape"/></w:sectPr></w:pPr><w:p>TEST</w:p><w:lastRenderedPageBreak/>'
)

Repro:

1. Add a table with a caption underneath it to a repo based on https://github.com/TrustedComputingGroup/specification-example
2. Render
3. Click a link from the LoT, it goes to the wrong place

The table I added:

# Table

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

Table: Zebra

• Extra thick line below tables
• Cross-reference appears in table caption in list of tables
• Tables that are not numbered still contribute to the table numbers of later tables (maybe this is ok)
• Images are too big by default
• Code font is a little too big
• Code blocks should have horizontal lines above and below them
• Optional: code blocks in the list of listings?
• Git graph is messed up in pdf but not github
• "Start of informative text" font should be a little smaller
• Mermaid diagrams should be centered
• Mermaid diagrams should be captioned
• Support a way for Mermaid diagrams to be cross-referenced
• Tables with rowspan and colspan have messed up borders
• Appendices page should be its own page
• Images are sometimes page width even when the resolution isn't high enough
• --- inside code blocks gets replaced with \newpage
• Remove trailing . from section numbers

Not many TCG docs have footnotes, but why not support it?

Small tables are sometimes rendered very small and centered on the page. We should left align all tables and make them take up more space if the cell widths are very small

On page 4 (of V0.10.4) it has a paragraph on "Key Words" and one for "Statement Type". These don't exist in current Guidance - which this document is. These should be removed.

• Vertical Specification/Reference text on first page should be bolded
• Disclaimers section should appear before table of contents
• Change history should appear before table of contents
• Table of contents format is clearly different (and, I bet, will be difficult to match exactly). At minimum, dotted lines between section headings and page numbers should be present for every entry.
• Default table format does not match.
• Top-level section headings should not be numbered
• Top-level section headings should be entirely uppercase
• Line spacing for "normal" text is in excess of 8pt (1.08)
• Remove spacing after section headings
• Margins appear larger than expected (should be 1.4 top (incl. orange bar) and 0.5 otherwise)
• Captions should be centered
• Missing delimeters for informative text ("Start of..." & "End of...")

I suspect this is due to having both a rowspan and a colspan for the cell.

We've gotten some feedback that users would prefer that words not get broken up across lines during typesetting.

Each drawio takes a couple of seconds to render. It should be possible to:

1. Not re-render an image if it's already been rendered (hash the content and not the filename)
2. Cache rendered images to github actions cache

Add about 3 points above and subtract about 3 points below.

This allows github diffs.

(Suggestion by @AndreasFuchsTPM)

Idea would be (in bash)

gitver=($(git describe --tags --always | tr '-' ' '))

specversion=”${gitver[0]}”

if [ “$(git branch)” = “main” ] then

specrevision=”${gitver[1]}”

else

specrevision=”${gitver[1]}-${gitver[2]}”

fi

Such that on the main branch we would only ever have version and revision (as number of commits since tag), but on branches where revision is not unique the commit id gets added as well.

Colspan (a row which spans multiple columns) is not possible in markdown tables.

As an alternative, it is possible to embed HTML in your markdown doc and use HTML attributes to achieve this. Is there any guidance on how markdown docs should be authored (i.e. features you should/shouldn't use)?

As a backlog item, we should consider general guidance on how TCG docs should be authored (best practices) to achieve certain desired formatting. Maybe that should go in the markdown repo though

If there is a ::: Note inside of a table cell, it's not placed vertically far enough from the line above it.

Sometimes the cached aux files need to be deleted in order for rendering to succeed:

Rendering PDF
Latexmk: Sometimes, the -f option can be used to get latexmk
  to try to force complete processing.
  But normally, you will need to correct the file(s) that caused the
  error, and then rerun latexmk.
  In some cases, it is best to clean out generated files before rerunning
  latexmk after you've corrected the files.
PDF output failed
Elapsed time: 4 seconds
! Undefined control sequence.
l.1 \xpginauxfiletrue
                     
? 
! Emergency stop.
l.1 

The workaround is to delete the caches from actions/caches and re-run the workflow, but this isn't very user-friendly.

Future versions of the tool should automatically recover from this state.

The GitHub releasing UI now has a "previous tag" option, which is used to generate release notes based on PRs since the given release. We should investigate if we can query this value during the release action, and generate the docx from the previous version and current version to automatically create a nice diff-doc.

In the case of code inside an example, it's a little odd that the headings are the same. I think a TCG section heading blue would look really good as the "Code:" heading on a code block.

#103 is nice from a style perspective but it does limit the type of markdown blocks that can be in a table cell. We should augment our filter to support at least lists inside table cells.

At a very rare rate of failure, sometimes we're getting hlines bleeding into the next one. This example is from a recent render of TPM Part 2, Definition of (UINT32) TPM_PT_PCR Constants.

A table cell's width doesn't seem to take the column separator width into account, so it wraps very close to the column line.

https://github.com/TrustedComputingGroup/Server-Internal/actions/runs/7615102098/job/20738830145

A version that only has a git hash gets marked Published instead of Draft.

If you have two rowspan cells next to each other, the vertical line between them is not fully drawn.