Other documents and teamwork: synthesis and challenges

Summary

This lesson closes the seventh unit, devoted to other documents and teamwork, and with it the course. It rebuilds the chain of principles and mechanisms that runs from the Beamer frame to the tagged PDF, pointing out at each link which principle is used and in which lesson it is established; it places what has been achieved in relation to the course plan and points out what remains after it; it repeats in its exit assessment the skills of the entry assessment; and it ends with six challenges, harder than the problems of the lessons, which require combining several units to compose a short article that brings together the whole course, turn it into a presentation, take its figure to a poster, diagnose a merge without conflict that changes a cross-reference, prepare it for arXiv and for a journal that compiles with pdfLaTeX, and write a preamble that serves at once an article, a presentation and a KOMA-Script report.

Learning objectives

Rebuild the order of the mechanisms of the unit, identifying the principle on which each one rests.
Explain why the same content changes genre, author and destination without being rewritten, and which decisions must nonetheless be taken at each change.
Predict what a frame with overlays, a class option, an exclusion file, a Git merge and a metadata declaration produce, and correct the source so that it produces what was intended.
Compose a short academic article that brings together the resources of the whole course, and adapt it to a presentation, to a poster and to the requirements of a publication destination.
Place what was learned in the course in relation to the writing courses of each discipline, which take it as their basis.

What the unit achieved

The unit set out to have the academic work built in the six previous units change genre, be written by several people and reach its destination without being redone. The purpose has been fulfilled by relying on what the introduction declared as known: logical markup, which says what each thing is and leaves its form to the class; one’s own preamble, which decides once what holds throughout the document; the relative measurements of figures; and the bibliographic database, which serves any genre that cites. With this, the path travelled can be read as a single chain in four stretches.

Presentations with Beamer

The lesson on presentations with Beamer showed that a presentation is a document like the others, with its own class: the page proportions are chosen with aspectratio, the language is declared as a class option so that it also reaches the theorem labels, and the sections, written between the frames, feed the table of contents through the same mechanism of runs as cross-references. It established that each overlay of a frame is a page of the PDF, so that \pause and the specifications in angle brackets can be counted, and that the handout option typesets each frame only once; it presented themes, columns, blocks and theorems; it brought biblatex’s short citation and a references frame to the slide; it explained why notes are repeated after every overlay; and it warned that Beamer typesets with the sans-serif family, so that \setmainfont does not change the slides.

Posters, letters and curriculum vitae

The lesson on posters, letters and the curriculum vitae deduced from the reading distance the minimum type size of a poster, $s \geq 7 \cdot \frac{d}{30}$ , and from the proportions of the A series a scale mock-up that is tested on an ordinary sheet; it composed the poster as a grid of boxes with the poster library of tcolorbox, whose base size is set with a single option; it treated the letter as a set of data, with letter and with the variables of scrlttr2; it presented moderncv, with its colour before its style and, with babel in Spanish, the option es-lcroman; and it composed an academic CV whose lists of publications come, filtered by keywords, from the same database as the articles. It ended by assigning to each genre the class that cannot leave out its distinctive feature.

Writing as a team

The lesson on writing as a team presented collaboration in Overleaf, with its comments, its track changes and its history, and version control with Git. From the fact that Git compares and merges files line by line it deduced the convention of writing one sentence per line, which does not change the PDF and lets two corrections in non-adjacent sentences merge by themselves; it excluded with a .gitignore the files that compilation regenerates, naming the PDF of the document instead of all PDFs, which may be figures; it taught how to resolve a conflict and how to check the resolution by compiling, because a merge without conflict can break a cross-reference; it showed the changes in the PDF with latexdiff; and it gathered the team’s conventions: a common preamble, a common database, one file per chapter and labels with prefixes.

Templates and publication

The lesson on templates and publication took the document to its destination. It adapted an article to a journal’s class by removing what the class decides and keeping the meaningful commands, and it pointed out the clashes, such as that of natbib, which elsarticle loads, with biblatex; it prepared a submission folder that compiles on its own; it explained that arXiv compiles the source and does not offer LuaLaTeX, so that the course’s document is submitted with XeLaTeX or adapted to pdfLaTeX; it produced a PDF/A with \DocumentMetadata, written before the class and with the PDF version the standard admits; and it tagged the PDF, with tagging=on, the alternative text of the figures and the language, so that someone who cannot see can also read it.

The following figure gathers the four stretches into a single chain. Each node of the column is a mechanism or a rule, numbered according to the order in which they rest on one another and joined by an arc to the earlier links it uses; around it float the supports, that is, the principles to which the chain turns again and again, each joined by a solid line to the links that rest on it and by a dotted line to the link where it is established, except those established in earlier units, which are drawn as rings. Clicking on a support highlights all the links that use it, and each link points to the lesson in which it is studied.

Supports of the chain

AWhat it is, not how it looks. Markup says what each element is, and the class and its options decide its form; this is why the content changes genre when the class changes. It is established in the second and third units. Admitted without proof in this unit.
BDecide once. What is decided in a single place (an option, a command of one’s own, a common preamble) changes throughout the document when it is changed there; what is copied by hand stops agreeing. It is established in the earlier units. Admitted without proof in this unit.
CRuns. The engine writes into the auxiliary files what it computes in one run and uses it in the next; those files are regenerated at every compilation. It is established in the first unit and refined in the third. Admitted without proof in this unit.
DRelative measurements. A measurement expressed in relation to the text, such as \linewidth or the sizes \large and \Huge, adapts to the place where it is used. It is established in the second and fifth units. Admitted without proof in this unit.
EOne database, many uses. Sources are described once in the bibliographic database, and each genre cites or lists them with the style and the filters that suit it. It is established in the sixth unit. Admitted without proof in this unit.
FWhat is valid gives no warning. The engine and its programs warn only about what they cannot process; a valid source that does not say what the author meant compiles without warning, and the defect shows only in the result. It is established in the fifth and sixth units. Admitted without proof in this unit.
GDistance decides. The angle a letter occupies decreases in proportion to the distance; the minimum type size grows with it. Established in: 6. Type size from distance.
HGit compares lines. Git compares and merges files line by line: it joins only the changes in non-adjacent lines, and declares a conflict if two changes touch the same line or adjacent lines. Established in: 11. Line-based differences and merges.

Segment 1 Presentations with Beamer
- Compose frames with titles, blocks, columns and theorems.
- Predict the pages produced by overlays, handouts and notes.
- Cite on the slide with the same database.
- Choose the typeface of a presentation knowing which family Beamer uses.
1. Frame and overlay as a page. Each frame produces one page per overlay: \pause and specifications such as <3-> or \only<2> fix how many; handout typesets one per frame, and a note is repeated after each overlay.
  Rests on: A (What it is, not how it looks). Proved in: Presentations with Beamer.
2. Sections and table of contents. \section is written between the frames, produces no page and feeds \tableofcontents, which is completed on the second compilation.
  Uses: 1. Frame and overlay as a page. Rests on: C (Runs). Proved in: Presentations with Beamer.
3. The language in the class. The language as a class option, english or french, reaches babel and Beamer’s translator; given only to babel, as in \usepackage[french]{babel}, the theorems are labelled in English, without warning.
  Uses: 1. Frame and overlay as a page. Rests on: B (Decide once), F (What is valid gives no warning). Proved in: Presentations with Beamer.
4. The short citation. On the slide one cites with biblatex’s short form, from the same database, and the full reference goes in a final frame.
  Uses: 1. Frame and overlay as a page. Rests on: E (One database, many uses). Proved in: Presentations with Beamer.
5. The sans-serif family. Beamer typesets with the sans-serif family: \setmainfont does not change the slides; one changes the sans-serif family or asks for the serif font theme, and professionalfonts leaves the mathematics untouched.
  Uses: 1. Frame and overlay as a page. Rests on: A (What it is, not how it looks), F (What is valid gives no warning). Proved in: Presentations with Beamer.
Segment 2 Posters, letters and curriculum vitae
- Compute the type size of a poster from the distance and test it on a mock-up.
- Compose a poster as a grid of boxes.
- Write letters with letter and scrlttr2.
- Compose a professional CV and an academic one from the database.
1. Type size from distance. At 30 cm the comfortable minimum is about 7 points; at a distance $d$ , in centimetres, the type size $s$ must satisfy $s \geq 7 \cdot \frac{d}{30}$ .
  Proved in: Posters, letters and curriculum vitae.
2. The scale mock-up. The A-series sizes have the same shape, and each side is divided by $\sqrt{2}$ at each step: an A0 reduced to A4 is read at a quarter of the intended distance.
  Uses: 6. Type size from distance. Rests on: G (Distance decides). Proved in: Posters, letters and curriculum vitae.
3. A grid of boxes. tcbposter divides the page into columns and rows, each \posterbox occupies a place in them, and fontsize sets the base size, on which all the relative sizes depend.
  Uses: 6. Type size from distance. Rests on: B (Decide once), D (Relative measurements), G (Distance decides). Proved in: Posters, letters and curriculum vitae.
4. The letter as data. letter and scrlttr2 receive the sender, the recipient, the date and the signature as data; scrlttr2 stores them in variables, such as place, and decides their position with its options.
  Rests on: A (What it is, not how it looks). Proved in: Posters, letters and curriculum vitae.
5. The CV from the database. moderncv asks for the colour before the style and, with babel in Spanish, for es-lcroman; the academic CV lists the publications with \nocite{*} and keyword filters that combine their conditions.
  Uses: 9. The letter as data, 4. The short citation. Rests on: E (One database, many uses), F (What is valid gives no warning). Proved in: Posters, letters and curriculum vitae.
Segment 3 Writing as a team
- Share a project in Overleaf or in a Git repository.
- Write so that other people’s changes do not collide.
- Exclude what is generated without losing what is not.
- Resolve a conflict, check it by compiling and show the changes.
1. Line-based differences and merges. Git records the changes of each commit as lines removed and added, and merges two branches without intervention when their changes touch separate lines.
  Proved in: Writing as a team.
2. One sentence per line. A single line break is a space, so writing one sentence per line does not change the PDF; the difference points to the sentence that changed, and two corrections in non-adjacent sentences merge by themselves.
  Uses: 11. Line-based differences and merges. Rests on: H (Git compares lines). Proved in: Writing as a team.
3. What is generated is not stored. The .gitignore excludes the auxiliary files and the document’s PDF by its name; *.pdf would also exclude the figures in PDF, without warning, and the document would not compile on another computer.
  Uses: 11. Line-based differences and merges. Rests on: C (Runs), F (What is valid gives no warning). Proved in: Writing as a team.
4. Resolve and compile. A conflict leaves markers in the file, which are resolved by hand; a merge without conflict can break a cross-reference, and that is why every merge is checked by compiling.
  Uses: 12. One sentence per line, 13. What is generated is not stored. Rests on: H (Git compares lines), F (What is valid gives no warning). Proved in: Writing as a team.
5. The changes in the PDF. latexdiff compares two versions of the source and writes a third which, once compiled, shows what was removed and what was added; the team’s conventions (common preamble and database, labels with prefixes) keep the comparison from filling up with differences of form.
  Uses: 14. Resolve and compile. Rests on: B (Decide once). Proved in: Writing as a team.
Segment 4 Templates and publication
- Adapt an article to a journal’s class.
- Prepare a submission folder that compiles on its own.
- Choose the engine and the bibliography the destination accepts.
- Produce an archival, tagged PDF.
1. Adapting to the template. One removes what the journal’s class decides (page, typeface, headings) and keeps the meaningful commands; packages the class already loads, such as natbib in elsarticle, may clash with one’s own.
  Uses: 3. The language in the class. Rests on: A (What it is, not how it looks), B (Decide once). Proved in: Templates and publication.
2. A source that compiles on its own. The submission folder contains everything the document reads and nothing more: sources, figures, the database or the .bbl, and no auxiliary files.
  Uses: 16. Adapting to the template, 13. What is generated is not stored. Rests on: C (Runs). Proved in: Templates and publication.
3. The destination decides the engine. arXiv compiles the source with LaTeX, pdfLaTeX or XeLaTeX, not with LuaLaTeX: the course’s document is submitted with XeLaTeX or adapted to pdfLaTeX, and is compiled beforehand with that engine; a submitted .bbl must be compatible with arXiv’s version of biblatex.
  Uses: 17. A source that compiles on its own, 4. The short citation. Rests on: E (One database, many uses), F (What is valid gives no warning). Proved in: Templates and publication.
4. PDF/A and its version. \DocumentMetadata goes before \documentclass; with pdfstandard=a-2b one adds pdfversion=1.7, because version 2.0 is not admissible for that part of the standard.
  Uses: 17. A source that compiles on its own. Rests on: F (What is valid gives no warning). Proved in: Templates and publication.
5. Tags, alternative text and language. tagging=on derives the structure of the PDF from meaningful markup; alt gives each figure what someone who cannot see it will hear, and lang declares the language.
  Uses: 19. PDF/A and its version. Rests on: A (What it is, not how it looks). Proved in: Templates and publication.

The end of the course. The chain ends where the document leaves its author’s hands: written with others, presented in several genres and delivered in the form its destination requires. With it the course ends.