Arbeidsflyt for publisering av artikler

En hyllest til mise-en-place

{{}}

Installer et nytt prosjekt fra paper-publishing-process med

• Automatisk kompilering av main.pdf, review-.pdf og diff-.pdf
• Git Tag-basert versjonering og generering av endringslogg
• CI/CD-pipeline med kompilering og nye releaser

{{< video src="compile-all.mp4" loop="true" autoplay="true" muted="true" >}}

{{}}

En frustrasjon fra da jeg først begynte å skrive artikler som skulle sendes inn til tidsskrifter og gå gjennom en vurderingssyklus var å kunne holde styr på hvilken versjon som ble sendt inn til hvilket tidspunkt. Hvilken versjon skal jeg svare på, hvilken versjon skal den oppdaterte versjonen differensieres mot? Dette var en svært manuell prosess hvor jobben med å holde styr på hva som skulle sendes inn i nyeste revisjon tidvis føltes like stor som selve skrivingen.

Heldigvis finnes det løsninger.

Oppsett av verktøy og repo

Alt skal kunne leve uavhengig av systemet man først utvikler på, så vi lager oss et Git-repo som alle filene kan leve i. I denne guiden kommer vi til å benytte GitHub sin workflow i utstrakt grad, så vi oppretter repoet der. Jeg kalte min paper-publishing-process, så la oss klone det ned:

Videre trenger vi å kunne installere alt av programvare, og til det bruker vi mise. Først må vi installere mise; besøk nettsiden, eller kjør følgende kommando:

Deretter oppretter vi fila mise.toml i prosjektet sin root:

Denne må vi gi tillatelse til mise til å bruke, mise trust, før vi installerer alt med mise install.

I den første commiten la jeg til en enkel lisensfil (MIT) og en .gitignore egnet for TeX-utvikling.

→ Se commit ce3150c.

La oss i samme slengen legge til noen filer som er behjelpelig med å holde repoet opp til en god standard hva angår formatering:

• tex-fmt.toml: Formatering av .tex og .bib
• .taplo.toml: Formatering av .toml
• .yamlfmt.yml: Formatering av .yml
• hk.pkl: Formatering og linting

Denne endringen oppdaterer også mise.toml og lager fila tex/main.tex.

→ Se commit b161e41.

Vi kan sjekke at alt så langt er som det skal:

Automatisk kompilering av TeX

Lokal kompilering med mise

Vi er nå klare til å jobbe med TeX-filene! Vi ønsker å kunne skrive i tex/main.tex, og hver gang vi lagrer så skal PDF-en oppdateres automatisk. Vi ser igjen til mise for å få denne funksjonaliteten.

→ Se commit e7127b4.

{{< details "Motivasjon for mise tasks" >}}

Vi legger i commiten over til en mise task kalt "localize-bib-paths". Motivasjonen bak det er at "compile" task (introdusert litt senere) vil kjøre den slik at når man utvikler lokalt vil alle referanser komme fra den globale hovedreferansen. Dette er nyttig i tilfeller hvor man ønsker å legge til en ny referanse i TeX-dokumentet som allerede finnes i hovedreferansen. Om man bruker en moderne editor vil den gi completion-forslag, noe som ikke vil være tilgjengelig i de genererte referansefilene for nye referanser.

{{< /details >}}

Vi kan nå kjøre

Den feiler! Dette er grunnet det først, litt spesielle valget vi gjør i denne arbeidsflyten.

Bibfish

For å kunne ha så minimale .bib-filer som mulig i repoet, blir alle generert fra en lokal "hovedreferansefil". Denne fila er det LOCAL_BIB_PATH verdien som vi la til i mise.toml peker på. Denne hovedreferansen er tiltenkt å være en fil som lever kun lokalt, og ikke i Git-repoet, og skal kunne levere referanser ikke bare til dette prosjektet, men til alle dine TeX-prosjekter! Bibfish vil da lese den og generere en referansefil basert kun på de referansene som finnes i en gitt TeX-fil.

Bibfish støtter de fleste vanlige siteringsformat (for eksempel \cite, \citet, osv.), men kan enkelt utvides med egne format. I mise.toml har vi lagt til citeA, og spesifiserer også cite, citet og citep (bibfish -c 'cite,citet,citep,citeA' -f main.tex {{ env.LOCAL_BIB_PATH }}.bib main.bib).

La oss fikse feilen fra i stad ved å

1. Legge mise.local.toml til i .gitignore
2. Spesifisere en lokal Bib-fil i mise.local.toml

{{}}

Merk at den lokale fila sin posisjon enten må være "absolutt" (/home/user/the-file), eller "relativ" fra tex-mappen, samt at den spesifiseres uten .bib.

{{< /callout >}}

Jeg la også til den lokale hovedreferansen her for å illustrere med et minimalt eksempel, men vanligvis ville jeg lagt den utenfor repoet. Legg også til

→ Se commit a149cdf.

Når vi nå forsøker å kompilere, ingen error!

BBL-filer og referanser i Git

La oss legge til noen referanser.

Vi lager oss også en generell compile-task i mise:

Når vi nå kjører mise watch compile vil en ny fil bli generert: tex/main.bbl. Denne er det vanlig å ignorere, men vi tenger denne i fremtiden, så vi fjerner den fra .gitignore.

Den inneholder en ny .bbl-fil, og .bib-fila har blitt oppdatert med én (og bare én) referanse, nemlig den vi la til i tex/main.tex!

→ Se commit 1a523ea.

Håndtering av TeX-pakker med tlmgr

Vi bruker tinytex som TeX-distribusjon i dette prosjektet. Den er som navnet antyder mye mindre enn den vanligere TeX-live/TeX-live-full. Det betyr også at vi litt oftere vil oppleve at pakker ikke er tilgjengelige, men det gir oss til gjengjeld mer kontroll. La oss bruke et knippe pakker som ikke er å finne i TinyTeX.

→ Se commit fe28c24 for oppdatert tex/main.tex og mise.toml.

Om du først endrer tex/main.tex med innholdet i commiten over og har mise watch compile kjørende burde den feile, og klage på at underscore ikke er tilgjengelig. Legg så til postinstall-hook i mise.toml, og kjør mise install.

Dette vil sørge for at diverse pakker installeres via tlmgr. Fordelen med dette oppsettet er at mange tidsskrifter er veldig kresne på hvilke pakker de aksepterer. Om man da har skrevet et langt manuskript som benytter mange pakker og som kompilerer fint lokalt fordi man har brukt TeX-live-full, kan det fort bli vanskelig å finne ut av hva som må bort om kompilering på tidsskriftet sin server krasjer.

Arbeidsflyt for lokal utvikling

Vi er nå i mål med arbeidsflyten for lokale TeX-filer! Kjør mise watch compile, skriv ned alle dine gode ideer, og hver gang tex/main.tex lagres vil kompileringen kjøre. Legg merke til hvordan tex/main.bib oppdateres i terminalvinduet øverst til høyre når jeg legger til og fjerner referanser.

{{< video src="compile.mp4" loop="true" autoplay="true" muted="true" >}}

Neste steg: automatisk kompilering på GitHub, støtte for versjonering via Git og rutiner for svar til tilbakemelding fra tidsskrifter.

CI/CD-pipeline på GitHub

Git commit hooks

Siden vi har verktøy for å formatere koden samt et fungerende hk oppsett, kan vi enkelt sette opp Git commit hooks:

{{}}

Siden mise run|watch compile gjør alle \bibliography{...} om til å bruke den lokale hovedreferansen, mens pre-commit hooken via hk gjør de om til å bruke de genererte bib-filene vil det oppstå konflikt mellom de.

Hver gang man lager en commit er det derfor lurt å stoppe mise watch compile, slik at den ikke skriver over før man er ferdig med commiten.

{{< /callout >}}

Automatisk bygging og release

For å sette opp CI/CD lager vi fila mise.ci.toml, samt tre filer i .github/workflows og .mise/tasks:

• .github/workflows/build.yml

  Kompilerer alle PDF-er for hver push til main-grenen på GitHub.

• .github/workflows/fix-bib-filepath.yml

  En ekstra sjekk som sørger for at rett bib-fil benyttes til å kompilere PDF-ene.

• .mise/tasks/package

  Legger alle filer som et tidsskrift ønsker i et arkiv, for enkel opplasting ved innsendelse.

→ Se commit 93c8487 for innholdet i filene.

Den commiten feilet faktisk i CI på GitHub. Her hadde jeg altså glemt at alle filer i .mise/tasks må være kjørbare (executable bit), det vil si jeg måtte

Jeg endret også på hvordan TinyTeX blir installert, og la til oppdatering av tlmgr i postinstall hook.

→ Se commit 06262fd.

Under ser vi at CI/CD kjørte uten error og ga oss en paper-assets artefakt.

{{