use github action to compile the document

[kellijohnson-NOAA]

Hi all, I successfully with suggestions from @k-doering-NOAA now have github actions compiling the sa4ss document and making the resulting pdf available for download. I think it would be pretty easy to enable the building of the latex code here if we want to go that route. Happy to help when the time is right.

[k-doering-NOAA]

Some additional ideas after spending some time trying to compile locally (thanks @chantelwetzel-noaa for the pointers!).

• The SS manual compiles well with miktex. Once I downloaded, I hit the button to compile through TexWorks and it compiled without error.
• I tried compiling with tinytex (which is a lightweight version of texlive) and was not successful. I had to download many packages manually which did work. However, I ran into a problem where the first picture file referenced in the .tex was not found; this could be a problem local to my machine, but I wasn't successful in troubleshooting.

Maybe a first step in setting this up would just be to get it working with miktex, since we know that will work locally? Then transition to texlive in order to build on what @kellijohnson-NOAA has learned.

There is a docker image for miktex: https://hub.docker.com/r/miktex/miktex that I think we could possibly start from. This essentially gives us a machine with miktex already set up.

@kellijohnson-NOAA does this seem like a good way forward to you?

[kellijohnson-NOAA]

The best example of compiling a latex document using an action is here.

[k-doering-NOAA]

Awesome reference, I did not know about that gh action workflow!

We might run into issues b/c this uses texlive, but this definitely seems like what we ultimately want.

[k-doering-NOAA]

Well, it turns out that example worked on the first try, like magic (unless I am missing something...). Great reference, @kellijohnson-NOAA !
https://github.com/nmfs-stock-synthesis/ss-documentation/blob/main/.github/workflows/build_latex_texlive.yml

Currently this job just runs manually, but we can change it if we decide to use it more. It should be a useful tool to get @chantelwetzel-noaa off the hook from being the only person who compiles.

[iantaylor-NOAA]

Nice work @k-doering-NOAA and @kellijohnson-NOAA getting this working.

For the record, I was able to get the manual to compile using tinytex on my laptop. I think there was some issue that I faced when I first tried, but with help from @chantelwetzel-noaa I got it worked out. So if that's an option anyone wants to pursue in the future, it's available.

[k-doering-NOAA]

Some notes to improve accessibility of the pdf created by gh actions, based on @kellijohnson-NOAA 's awesome work with sa4ss:

• Put this at the top of the latex file:
  https://github.com/nwfsc-assess/sa4ss/blob/master/inst/rmarkdown/templates/sa/skeleton/input_accessability.tex

• need this in repo or to get it from gh. This is a lua filter that adds tags to document that are necessary for screen readers. Probably need to still add custom code to this (as Kelli has written) so tables can be read:
  https://github.com/klpn/accpdf/blob/master/common/tagged-filter.lua

• Call the lua filter above via command line args. Example of how this is done in sa4ss:
  https://github.com/nwfsc-assess/sa4ss/blob/master/R/utils.R#L15 call filter through bookdown

• Note that this pkg is needed to compile with the filter. It may not be part of the standard latex distribution, so may need to download this separately, if fails in the job: https://ctan.org/pkg/pdfmanagement-testphase?lang=en

[k-doering-NOAA]

@kellijohnson-NOAA , I got a little bit stuck with trying to use the lua filter. I think it is because the call needs to be passed to pandoc, but I am passing it to the latex engine. I'm kind of lost because I'm not even sure if pandoc is being used?

Here are the options available for the github action to compile: https://github.com/xu-cheng/latex-action#inputs . I tried passing the command to call the lua filter to args, but got an error Latexmk: -lua-filter=tagged-filter.lua bad option

Any ideas on how to pass it to pandoc? Or how to know if I'm using pandoc? I still don't quite get the sequence of events that happens when compiling .tex.

[chantelwetzel-noaa]

@kellijohnson-NOAA is definitely the expert here but I will pitch in what I know. If you have Rstudio on you machine pandoc will be available through the Rstudio terminal. However, you can also have pandoc installed separately. To check to see if it is on your machine open up the cmd and then enter pandoc --version. This should return the version on you machine if it is installed. If you do have pandoc installed, you should then make sure it is available in you PATH. Let us know what you see and we can go from there.

[k-doering-NOAA]

Thanks, @chantelwetzel-noaa - I should have said that I am trying to do this in a github action (https://github.com/nmfs-stock-synthesis/ss-documentation/blob/build_access/.github/workflows/build_latex_texlive.yml) . It is good to know about the pandoc command, thanks so much, that is a helpful debugging tool.

[kellijohnson-NOAA]

So there are different versions of latex and the action that you are calling uses pdflatex. We want to use lualatex. I didn't read a ton of the document that you linked to, thank you btw, but I did see that lualatex is an option via latexmk_use_lualatex.

[k-doering-NOAA]

Thanks @kellijohnson-NOAA and @chantelwetzel-noaa! I figured out a few things:

• I was able to use lulatex, as Kelli suggested.
• I think I don't need to use the lua pandoc filter. I think it was necessary for a4ss because pandoc is used to convert markdown; I don't think we need to use pandoc because we are dealing directly with tex files. Instead, I was able to use tagpdf to tag the pdf.

This certainly reduced the number of errors with the PAC3 (an accessibility checker), although some still exist:
SS330_User_Manual_PAC_Report.pdf

Some of these I think are issues Kelli has run into as well and may be tricky to fix (table of contents issues, wanting annotations for links). Some are probably easily fixable, though.

[chantelwetzel-noaa]

@k-doering-NOAA That is great to hear! When this document was originally created 508-compliance was not considered. We should look to see what changes can be made now that tagpdf is available to see if we can improve the document accessibility. This could be done slowly and incrementally but something that we should definitely consider when making edits to the document.

[k-doering-NOAA]

closing since we are successfully compiling the manual now with github actions.