From 08eacbe545506e554ecfa71b108e64366413dd58 Mon Sep 17 00:00:00 2001 From: "Allen D. Householder" Date: Wed, 3 May 2023 11:07:51 -0400 Subject: [PATCH] add github workflow to generate html and pdf artifacts on push to develop and main branches when docs change (#231) merging this in, we can adjust going forward if necessary --- .github/workflows/pandoc_html_pdf.yaml | 113 + doc/Makefile | 126 + doc/README.md | 58 +- doc/crossref-how-to | 11 - doc/crossref-how-to.md | 16 + doc/{ => obsolete}/compile-html-citeproc.sh | 0 doc/{ => obsolete}/compile-pdf.sh | 4 +- doc/{ => obsolete}/compile-v1.sh | 0 doc/pdf-styling.yaml | 3 +- doc/reference-how-to | 27 - doc/reference-how-to.md | 31 + doc/ssvc_v2-0.html | 4576 ++++++++++++++++--- doc/ssvc_v2-0.pdf | Bin 0 -> 468509 bytes 13 files changed, 4178 insertions(+), 787 deletions(-) create mode 100644 .github/workflows/pandoc_html_pdf.yaml create mode 100644 doc/Makefile delete mode 100644 doc/crossref-how-to create mode 100644 doc/crossref-how-to.md rename doc/{ => obsolete}/compile-html-citeproc.sh (100%) rename doc/{ => obsolete}/compile-pdf.sh (92%) rename doc/{ => obsolete}/compile-v1.sh (100%) delete mode 100644 doc/reference-how-to create mode 100644 doc/reference-how-to.md create mode 100644 doc/ssvc_v2-0.pdf diff --git a/.github/workflows/pandoc_html_pdf.yaml b/.github/workflows/pandoc_html_pdf.yaml new file mode 100644 index 00000000..b7a045c4 --- /dev/null +++ b/.github/workflows/pandoc_html_pdf.yaml @@ -0,0 +1,113 @@ +name: pandoc_html + +on: + # manual trigger (for testing) + workflow_dispatch: + # trigger on push to doc folder on main or develop branches + push: + branches: + - develop + - main + paths: + - doc/** + - .github/workflows/pandoc_html_pdf.yaml + +# todo version numbers should be read from a file within the repository +env: + MAJOR: 2 + MINOR: 0 + FIX: 5 + TITLE_PREFIX: "SSVC" + COMPILE_DATE: "${{ github.event.head_commit.timestamp }}" + BIBLIOGRAPHY: "doc/md_src_files/sources_ssvc.bib" + PDF_STYLING: "doc/pdf-styling.yaml" + MD_IN: "doc/ssvc_tmp.md" + HTML_OUT: "ssvc_vMAJ-MIN.html" + EMOJI_REPLACEMENTS: "doc/emoji-replacements.sed" + +jobs: + convert_via_pandoc: + runs-on: ubuntu-22.04 + steps: + - uses: actions/checkout@v3 + + - name: Get short commit hash + id: vars + run: echo "sha_short=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT + + - name: Concatenate markdown files and fix graphics links + run: cat doc/md_src_files/*.md | sed -e 's/\.\.\/graphics/doc\/graphics/g' > ${{ env.MD_IN }} + + # we have to set these at runtime because they depend on the version number + - name: Set environment variables + run: | + echo "TITLE=\"Prioritizing Vulnerability Response: A Stakeholder-Specific Vulnerability Categorization (SSVC) version ${{ env.MAJOR }}.${{ env.MINOR }}.${{ env.FIX}}-${{ steps.vars.outputs.sha_short }}\"" >> $GITHUB_ENV + echo "HTML_OUT=ssvc_v${{ env.MAJOR }}-${{ env.MINOR }}-${{ env.FIX}}-${{ steps.vars.outputs.sha_short }}.html" >> $GITHUB_ENV + echo "PDF_OUT=ssvc_v${{ env.MAJOR }}-${{ env.MINOR }}-${{ env.FIX}}-${{ steps.vars.outputs.sha_short }}.pdf" >> $GITHUB_ENV + + - name: Convert markdown to html using pandoc + uses: docker://pandoc/latex:latest + with: + args: >- # allows you to break string into multiple lines + --standalone + --embed-resources + --to html + --from markdown_github+citations+table_captions+implicit_figures+link_attributes + --citeproc + --bibliography ${{ env.BIBLIOGRAPHY }} + --metadata title=${{ env.TITLE }} + --metadata date="${{ env.COMPILE_DATE }}" + --title-prefix ${{ env.TITLE_PREFIX }} + --metadata-file ${{ env.PDF_STYLING }} + --output ${{ env.HTML_OUT }} + ${{ env.MD_IN }} + + - name: Upload markdown artifact if html failed + uses: actions/upload-artifact@v3 + if: failure() + with: + name: markdown + path: ${{ env.MD_IN }} + + - name: Upload html artifact + uses: actions/upload-artifact@v3 + with: + name: output + path: ${{ env.HTML_OUT }} + + - name: Replace Emojis in Markdown + run: | + sed -f ${{ env.EMOJI_REPLACEMENTS }} ${{ env.MD_IN }} > __tmp.md + mv __tmp.md ${{ env.MD_IN }} + + - name: Convert markdown to pdf using pandoc + uses: docker://pandoc/latex:latest + with: + args: >- # allows you to break string into multiple lines + --standalone + --from markdown_github+citations+yaml_metadata_block+tex_math_dollars + --to pdf + --citeproc + --pdf-engine=xelatex + --bibliography ${{ env.BIBLIOGRAPHY }} + --table-of-contents + --metadata title=${{ env.TITLE }} + --metadata date="${{ env.COMPILE_DATE }}" + --title-prefix ${{ env.TITLE_PREFIX }} + --metadata-file ${{ env.PDF_STYLING }} + --output ${{ env.PDF_OUT }} + ${{ env.MD_IN }} + + - name: Upload markdown artifact if pdf failed + uses: actions/upload-artifact@v3 + if: failure() + with: + name: markdown + path: ${{ env.MD_IN }} + + - name: Upload pdf artifact + uses: actions/upload-artifact@v3 + with: + name: output + path: ${{ env.PDF_OUT }} + diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..6cbd45f2 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,126 @@ +# Makefile + +SHELL=/bin/bash +# +# Converts Markdown to other formats (HTML, PDF, DOCX, RTF, ODT, EPUB) using Pandoc +# based on https://gist.github.com/kristopherjohnson/7466917 +# +# +# Run "make" (or "make all") to convert to all other formats +# +# Run "make clean" to delete converted files + +# versioning +# need a better way of automatically updating version numbers +MAJOR=2 +MINOR=0 +# these have the common meanings from semantic versioning +# major should be incremented with content changes that introduce incompatibilities +# minor should be incremented for meaningful changes that do not break compatibility +FIX=5 +# fix version needs to be incremented with every commit + +#versioning across different content is a bit complicated. +# The PDF major.minor should match any schema, tree, or other supporting document version +# This means if the major.minor version changes, the schemas need a numbering change +# The fix version for the schema and the PDF document may mismatch + +HOME:=$(shell pwd) +OUTDIR=$(HOME) +SRC=./md_src_files + +TITLE:="Prioritizing Vulnerability Response: A Stakeholder-Specific Vulnerability Categorization (SSVC version $(MAJOR).$(MINOR).$(FIX))" +TITLE_PREFIX:="SSVC" +COMPILE_DATE:="Compiled `date -u`" +PDF_STYLING:=pdf-styling.yaml +BIBLIOGRAPHY:=$(SRC)/sources_ssvc.bib + +# TODO decide whether to include FIX level in file name or not +#PDF_OUT:=$(OUTDIR)/ssvc_v$(MAJOR)-$(MINOR)-$(FIX).pdf +#HTML_OUT:=$(OUTDIR)/ssvc_v$(MAJOR)-$(MINOR)-$(FIX).html +PDF_OUT:=$(OUTDIR)/ssvc_v$(MAJOR)-$(MINOR).pdf +HTML_OUT:=$(OUTDIR)/ssvc_v$(MAJOR)-$(MINOR).html + +EMOJI_REPLACEMENTS:=$(HOME)/emoji-replacements.sed + +# we need +GFX=graphics +GFX_LINK=../$(GFX) + +# Convert all files in this directory that have a .md suffix +SOURCE_DOCS := $(wildcard $(SRC)/*.md) + +EXPORTED_DOCS=$(PDF_OUT) $(HTML_OUT) + +# where to find things +RM:=/bin/rm +SED:=sed +PANDOC:=`which pandoc` + +# HTML can handle emojis and not LaTeX commands, so the markdown files have emoji +# However, it is really hard to embed emoji into PDFs in a platform-independent way +# Apple Emoji font and Noto Emoji font are the two options, basically, and as of Apr 2022 +# most devices seem to have one or the other. +# In general, LaTeX is bad at emojis, but the twemojis package might make it OK. +# However, twemojis is not a default package yet, so avoiding that for now. +# So the best available option is to temporarily replace them with LaTeX commands +# Pandoc will read from stdin if no input files are provided, so sed works inline. +REPLACE_EMOJI=$(SED) -f $(EMOJI_REPLACEMENTS) $(SOURCE_DOCS) + + + +PANDOC_OPTIONS=--standalone \ + --citeproc \ + --bibliography=$(BIBLIOGRAPHY) \ + --metadata=title:$(TITLE) \ + --title-prefix=$(TITLE_PREFIX) \ + --metadata=date:$(COMPILE_DATE) \ + --metadata-file=$(PDF_STYLING) \ + +# --from should use gfm, but gfm+citations is not supported +# so this method should perhaps be considered slightly unstable. +# This citation syntax won't render on github +# but the @ citation syntax shouldn't interfere with @ mentions +# GFM only allows @ mentions in issues and pull requests +# https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown +# documentation for citation processing: +# https://pandoc.org/MANUAL.html#citations + + +PANDOC_PDF_OPTIONS=--to=pdf \ + --from=markdown_github+citations+yaml_metadata_block+tex_math_dollars \ + --pdf-engine=xelatex \ + --table-of-contents \ + -o $(PDF_OUT) + +PANDOC_HTML_OPTIONS=--to=html \ + --self-contained \ + --from=markdown_github+citations+table_captions+implicit_figures+link_attributes \ + -o $(HTML_OUT) + + +# Pattern-matching Rules + +pdf : $(SOURCE_DOCS) + @echo "Create temporary link so pandoc can find graphics" + pushd .. && ln -s $(HOME)/$(GFX) $(GFX) && popd + @echo "Replace emoji with text and convert to PDF" + $(REPLACE_EMOJI) | $(PANDOC) $(PANDOC_OPTIONS) $(PANDOC_PDF_OPTIONS) + @echo "Remove temporary link to graphics" + - $(RM) $(GFX_LINK) + +html: $(SOURCE_DOCS) + @echo "Create temporary link so pandoc can find graphics" + pushd .. && ln -s $(HOME)/$(GFX) $(GFX) && popd + $(PANDOC) $(PANDOC_OPTIONS) $(PANDOC_HTML_OPTIONS) $(SOURCE_DOCS) + @echo "Remove temporary link to graphics" + - $(RM) $(GFX_LINK) + +# Targets and dependencies + +.PHONY: all clean + +all : pdf html + +clean: + - $(RM) $(EXPORTED_DOCS) \ No newline at end of file diff --git a/doc/README.md b/doc/README.md index 7e0d392e..6461c65b 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,22 +1,46 @@ # Definitional documents -This folder contains the text documents that describe the decision process, the decision points, the possible decision values, and the decision trees that should be used to reach prioritization decisions. - -The current draft should be compiled into `ssvc_v#.html` for easy viewing, though it may be behind the markdown source by a couple commits. - -The documents are in markdown for easy editing. -All the source files needed to create a polished document are in the `md_src_files` folder. -The work on version 1 started with the version of the paper published at [WEIS 2020](https://weis2020.econinfosec.org/wp-content/uploads/sites/8/2020/06/weis20-final6.pdf). -A copy of this document and other prior drafts is in the `pdfs` folder. - - -The `*.md` files should be limited to one file per section, for easier editing and merging. The current numbering scheme is important so the command line `*` ingests the files in the right order. Three digits (`010`, etc.) are used in case new sections need to be interleaved. A substantive edit to a section should probably be renamed `011`, etc., but we don't have guidance on what counts as "substantive" yet. A total re-write wold be, though. - -The `compile*.sh` files contain pandoc command line for creating a single HTML document from the markdown. It also contains the document metadata (title, authors, date) as command-line arguments. - -The `*how-to` files contain discussion on document composition and style. Please align any commits with the existing how-to guidance. At present (Aug 2020), the how-to guidance is not yet fixed, but it should only change with community discussion. - +This folder contains the text documents that describe the decision process, the decision points, the possible decision +values, and the decision trees that should be used to reach prioritization decisions. + +The current draft should be compiled into `ssvc_v#.html` for easy viewing, though it may be behind the markdown source +by a couple commits. + +The documents are in markdown for easy editing. +All the source files needed to create a polished document are in the [`md_src_files`](md_src_files) folder. +The work on version 1 started with the version of the paper published +at [WEIS 2020](https://weis2020.econinfosec.org/wp-content/uploads/sites/8/2020/06/weis20-final6.pdf). +A copy of this document and other prior drafts is in the `pdfs` folder. + +The `*.md` files should be limited to one file per section, for easier editing and merging. The current numbering scheme +is important so the command line `*` ingests the files in the right order. Three digits (`010`, etc.) are used in case +new sections need to be interleaved. A substantive edit to a section should probably be renamed `011`, etc., but we +don't have guidance on what counts as "substantive" yet. A total re-write wold be, though. + +The [`Makefile`](Makefile) contains pandoc commands line for creating a single HTML and PDF document from the markdown. It also +contains the document metadata (title, authors, date) as command-line arguments. You can: + +```bash +$ make all +``` +to produce both HTML and PDF output, or do either of +```bash +$ make pdf +$ make html +``` +for the respective output. + +Note that the `Makefile` was used as the basis for the github action +[`.github/workflows/pandoc_html_pdf.yaml`](./github/workflows/pandoc_html_pdf.yaml), which should be maintained in sync +with the `Makefile` in the future. + +The `*how-to` files contain discussion on document composition and style. Please align any commits with the existing +how-to guidance. At present (Aug 2020), the how-to guidance is not yet fixed, but it should only change with community +discussion. # Thank you -The authors thank the following people for helpful comments on prior drafts: Michel van Eeten as shepherd and the anonymous WEIS reviewers; attendees at A Conference on Defense (ACoD), Austin TX 2020; Dale Peterson, Ralph Langer, and attendees at S4, Miami FL 2020; Muhammad Akbar and Manish Gaur (VMWare); David Oxley (McAfee). + +The authors thank the following people for helpful comments on prior drafts: Michel van Eeten as shepherd and the +anonymous WEIS reviewers; attendees at A Conference on Defense (ACoD), Austin TX 2020; Dale Peterson, Ralph Langer, and +attendees at S4, Miami FL 2020; Muhammad Akbar and Manish Gaur (VMWare); David Oxley (McAfee). diff --git a/doc/crossref-how-to b/doc/crossref-how-to deleted file mode 100644 index 6c9a392d..00000000 --- a/doc/crossref-how-to +++ /dev/null @@ -1,11 +0,0 @@ -Cross references to other sections can be accomplished with the []() commands for links. -The text to appear goes in []. -The heading to link to goes in () -Full heading text, lowercased, with - instead of spaces. -for example [Section 2](#current-state-of-practice) -See: https://gist.github.com/asabaylus/3071099 - -To create an arbitrary anchor, use HTML, e.g.: - -https://stackoverflow.com/questions/5319754/cross-reference-named-anchor-in-markdown - diff --git a/doc/crossref-how-to.md b/doc/crossref-how-to.md new file mode 100644 index 00000000..d8d3bee6 --- /dev/null +++ b/doc/crossref-how-to.md @@ -0,0 +1,16 @@ +# How To Use Cross References + +- Cross references to other sections can be accomplished with the `[text](link)` syntax for links. + - The text to appear goes in `[]` + - The heading to link to goes in `()` +- Use full heading text, lowercased, with `-` instead of spaces. + - for example [Section 2](#current-state-of-practice) + - See: https://gist.github.com/asabaylus/3071099 + +## To create an arbitrary anchor +- use HTML, e.g.: +```html + +``` +- see also https://stackoverflow.com/questions/5319754/cross-reference-named-anchor-in-markdown + diff --git a/doc/compile-html-citeproc.sh b/doc/obsolete/compile-html-citeproc.sh similarity index 100% rename from doc/compile-html-citeproc.sh rename to doc/obsolete/compile-html-citeproc.sh diff --git a/doc/compile-pdf.sh b/doc/obsolete/compile-pdf.sh similarity index 92% rename from doc/compile-pdf.sh rename to doc/obsolete/compile-pdf.sh index 34cf505e..6828faba 100755 --- a/doc/compile-pdf.sh +++ b/doc/obsolete/compile-pdf.sh @@ -33,11 +33,11 @@ pandoc --standalone \ --pdf-engine=xelatex \ --bibliography="$src/sources_ssvc.bib" \ --table-of-contents \ - -M title="Prioritizing vulnerability response: A stakeholder-specific vulnerability categorization (Version 2.0)" \ + -M title="Prioritizing Vulnerability Response: A Stakeholder-Specific Vulnerability Categorization (SSVC version $major.$minor.$fix)" \ -T "SSVC" \ -M date="Compiled `date -u`" \ --metadata-file=pdf-styling.yaml \ - -o "ssvc_$major2-$minor-$fix.pdf" \ + -o "ssvc_$major-$minor-$fix.pdf" \ # --from should use gfm, but gfm+citations is not supported # so this method should perhaps be considered slightly unstable. diff --git a/doc/compile-v1.sh b/doc/obsolete/compile-v1.sh similarity index 100% rename from doc/compile-v1.sh rename to doc/obsolete/compile-v1.sh diff --git a/doc/pdf-styling.yaml b/doc/pdf-styling.yaml index 03b602da..38371141 100644 --- a/doc/pdf-styling.yaml +++ b/doc/pdf-styling.yaml @@ -8,7 +8,7 @@ author: - Vijay Sarvapalli - Deana Shick - Laurie Tyzenhaus -documentclass: scrreprt +documentclass: report classoption: - 10pt - letterpaper @@ -20,5 +20,4 @@ secnumdepth: 4 geometry: - top=1in - bottom=1in -mainfont: Times ... diff --git a/doc/reference-how-to b/doc/reference-how-to deleted file mode 100644 index 4398c9f2..00000000 --- a/doc/reference-how-to +++ /dev/null @@ -1,27 +0,0 @@ -Would most prefer using pandoc-citeproc. -GFM does not natively support bibtex citations. However, the pandoc markdown syntax is to use @referencetag. -Documentation for citation processing: -# https://pandoc.org/MANUAL.html#citations - -The @ citation syntax shouldn't interfere with @ mentions. GFM only allows @ mentions in issues and pull request. -# https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown - -So the preferred citation method is two steps: -(1) Search sources_ssvc.bib for the desired reference -(2a) if it's there, use [@referencetag] in the markdown text. For example, the tag in the entry beginning with - @book{simon1996sciences, -is simon1996sciences -(2b) If it's not there, add it to the correct subpart of the bibtex file. (books are together, articles are together, CVSS publications are together, etc.) Use authorYYYYword style for the tags (this is the default Google Scholar naming style, which is a good place to get decently formatted bibtex that you can tidy up). Then use the [@referencetag] in the markdown text. - - -Though the [@tag] command won't reference on github, the compile-citeproc.sh script has the right pandoc commands to create a pretty HTML file with a proper references section. - -Do not use footnotes. -There is a markdown style for footnotes (https://pandoc.org/MANUAL.html#footnote) -But right now GFM doesn't support that. -Footnotes and asides that were not references in v1 have been written in to the flow of the text. - - - - - diff --git a/doc/reference-how-to.md b/doc/reference-how-to.md new file mode 100644 index 00000000..20552295 --- /dev/null +++ b/doc/reference-how-to.md @@ -0,0 +1,31 @@ +# Notes on References + +- Would most prefer using pandoc-citeproc. +- GFM does not natively support bibtex citations. However, the pandoc markdown syntax is to use @referencetag. +- Documentation for citation processing: + - https://pandoc.org/MANUAL.html#citations +- The @ citation syntax shouldn't interfere with @ mentions. GFM only allows @ mentions in issues and pull request. + - https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown + +## The preferred citation method is as follows: + +1. Search [`md_src_files/sources_ssvc.bib`](md_src_files/sources_ssvc.bib) for the desired reference +2. If it's there, use `[@referencetag]` in the markdown text. For example, the tag in the entry beginning with +```bibtex + @book{simon1996sciences, +``` +is `simon1996sciences` +3. If it's not there, add it to the correct subpart of the bibtex file. (books are together, articles are together, CVSS publications are together, etc.) Use authorYYYYword style for the tags (this is the default Google Scholar naming style, which is a good place to get decently formatted bibtex that you can tidy up). Then use the [@referencetag] in the markdown text. + + +Though the `[@tag]` command won't reference on github, the `html` target in the `Makefile` has the right pandoc commands to create a pretty HTML file with a proper references section. + +## Do not use footnotes. +- There is a markdown style for footnotes (https://pandoc.org/MANUAL.html#footnote) + - But right now GFM doesn't support that. +- Footnotes and asides that were not references in v1 have been written in to the flow of the text. + + + + + diff --git a/doc/ssvc_v2-0.html b/doc/ssvc_v2-0.html index 05498059..3b510aa4 100644 --- a/doc/ssvc_v2-0.html +++ b/doc/ssvc_v2-0.html @@ -4,8 +4,15 @@ - - SSVC – Prioritizing vulnerability response: A stakeholder-specific vulnerability categorization (DRAFT version 2.0) + + + + + + + + + SSVC – Prioritizing Vulnerability Response: A Stakeholder-Specific Vulnerability Categorization (SSVC version 2.0.5)