# Technical Writing on Windows 10/11 --- author: - Russell D. Brunelle date: 'January 1, 2024' subtitle: | via a state-of-the-art open-source toolchain abstract: | This tutorial teaches you to create beautiful PDF documents from simple text files. Using Notepad++ you write Markdown that's backed up via Git, Pandoc typesets your Markdown via LaTeX while adding any flowcharts written in Mermaid, and all of this runs (without needing internet access) via VirtualBox on a virtual Debian Linux machine that's accessed via PuTTY. ... ## Our goal ![Your Screen](pandoc-debian-ui.png){#fig:ui width=100%} In the screen shown in [@fig:ui], you'll write on the left, issue the typesetting command at bottom right, then proofread at top right. ## Configuring your basic tools ### Notepad++ #### Setup Install Notepad++ from [`https://notepad-plus-plus.org`](https://notepad-plus-plus.org). I recommend making the following changes to Notepad++ right away ("Line ending" and "Tab Settings" admittedly being the only *truly* essential ones): * View → Word wrap → [checked] * Settings → Style Configurator... → 1. Select theme → Default (stylers.xml) 2. Language → Global Styles 3. Style → Global override → Font name → Consolas 4. Style → Default Style → Font name → Consolas 5. Save & Close * Settings → Preferences... → 1. General → Toolbar → Hide 2. Editing → Caret Settings → Width → 3 3. Editing → Current Line Indicator → None 4. Margins/Border/Edge → Fold Margin Style → None 5. Margins/Border/Edge → Line Number → Constant width 6. New Document → Format (Line ending) → Unix (LF) 7. Language → Tab Settings → Replace by space → [checked] 8. Highlighting → Smart Highlighting → Enable → [unchecked] 9. Print → Print line number → [unchecked] 10. Backup → Enable session snapshot and periodic backup → [choose]^[If your computer is stable, you're in the habit of regularly saving, and you'll be keeping your work under version control, then you may prefer to uncheck this.] 11. Auto-Completion → Enable auto-completion on each input → [unchecked] 12. Auto-Completion → Function parameters hint on input → [unchecked] 13. Close #### Spelling Spell check is provided via a plugin. Here's how you activate that plugin: 1. Plugins → Plugins Admin... → Available → DSpellCheck → [checked] → Install → Yes 2. Plugins → DSpellCheck → Settings... → Simple → Download... → [check desired language] → Install Selected → OK → Apply → OK 3. Plugins → DSpellCheck → Settings... → Advanced → Underline Style → Straight Box → Apply → OK 4. Plugins → DSpellCheck → Spell Check Document Automatically → [choose] #### Color All of the above only has to be done once. But choosing one of the following two Markdown color modes is something you'll probably want to do every time you open a Markdown file for substantial work. * If you're in ordinary light conditions: 1. Language → Markdown (preinstalled) 2. Settings → Preferences... → Dark Mode → Light mode → Close * If you're in very low light conditions: 1. Language → Markdown (preinstalled dark mode) 2. Settings → Preferences... → Dark Mode → Dark mode → Close If you chose the low light option above, then you'll probably also want to do most of your work in full screen mode. The F11 key toggles that. ### VirtualBox Install it from [`https://www.virtualbox.org`](https://www.virtualbox.org). Two quick comments: 1. You may notice that a fresh installation of VirtualBox creates a default host-only VirtualBox network. There's no harm in ignoring this virtual network, but for our purposes there's also no harm in removing it via "File → Tools → Network Manager"; this virtual network is only useful if not only will you be running multiple virtual machines simultaneously, but those virtual machines will need to communicate *with each other*. We're not doing anything remotely like that. 2. VirtualBox can't run on Windows PCs with ARM CPUs (i.e., the radically different type of CPU normally found in smartphones). But "Windows on ARM" PCs are currently only a *very* small part of the total Windows PC market, and it's similarly unlikely this limitation will apply to you. ### PuTTY #### Setup Install it from [`https://www.chiark.greenend.org.uk/~sgtatham/putty/`](https://www.chiark.greenend.org.uk/~sgtatham/putty/). I recommend creating within PuTTY two saved sessions (one for "root" logins and one for ordinary user account logins) as follows: * Session * Host Name: 127.0.0.1 * Port: 10022 * Close window on exit: Always * Terminal * Bell * Action to happen when a bell occurs: None * Taskbar/caption indication on bell: Steady * Window * Appearance * Font: Consolas * Selection * Ctrl + Shift + {C,V}: System clipboard * Colours * Use system colours: [checked] * Connection * Data * Auto-login username: [root for your first saved session, and your preferred ordinary username for your second saved session] #### Use Please note that you'll use an accompanying application called "Pageant" (which comes with your PuTTY installation) to actually initiate one of the login sessions you just configured. Using Pageant is more elegant, since: * to initiate an SSH login you can simply right-click Pageant in the Windows system tray and pick the session you want under "Saved Sessions." * logging out of any particular session doesn't cause Pageant to exit. Because Pageant will be an everyday application, I strongly recommend making it always visible in the Windows system tray. Here's how you do that, once Pageant is running: Windows 11 : Right-click the taskbar, select "Taskbar settings," select "Other system tray icons," and finally switch "PuTTY SSH authentication agent" from Off to On. Windows 10 : Same as Windows 11, except what you select in "Taskbar settings" is named "Select which icons appear on the taskbar." ## Creating your virtual machine ### Downloading its installation "disc" You'll need to download a boot disc image in order to install your virtual machine's operating system. The correct file has a file name beginning simply with "debian" (not "debian-edu" or "debian-mac") and ending with ".iso", from the following list: [`https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/`](https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/) ### Defining its virtual hardware Start VirtualBox, and create the virtual hardware for your virtual machine as follows: 1. Machine → New... * Name: Debian {version}^[Including the Debian version number like this isn't a requirement, but I think it's helpful. If, for example, your disc image's filename were `debian-12.4.0-amd64-netinst.iso` then this number would be 12, and hence you'd type: Debian 12] * ISO Image → Other... → [the boot image you just downloaded] → Open * Skip Unattended Installation: [checked] * Disk Size: 17.00 GB (minimum) * Pre-allocate Full Size: [checked] 2. Machine → Settings... * Network → Adapter 1 → Advanced → Port Forwarding → Add → ssh / TCP / 127.0.0.1 / 10022 / [blank] / 22 → OK * Shared Folders * Add → Folder Path → Other... → [folder named "Downloads" (might be the default location for your web browser's downloads)] → Select Folder → OK * Add → Folder Path → Other... → [folder named "Work" (might be where you keep all the stuff you're actively working on)] → Select Folder → OK ### Installing its operating system Its virtual hardware having now been created, and its virtual CD-ROM drive having now been loaded with a virtual installation disc, you can proceed to installing your virtual machine's operating system. Issue the VirtualBox command "Machine → Start → Normal Start" to begin the process; you'll be going with either the default or with the only sensible choice at every subsequent installation prompt, except as noted below: * At the main installer menu: pick "Install" rather than "Graphical install" * Domain name: localdomain * Software selection: deselect "Debian desktop environment" and "GNOME" * Device for boot loader: /dev/sda Note that during this operating system installation process you're guided through creating two different login accounts: one "root" user account, and one ordinary user account. Once you've finished configuring your virtual machine you'll basically never use the former; it's the latter you'll use on a day-to-day basis to issue the `pandoc` commands that will typeset documents from your Markdown-format text files, the `mmdc` commands that will generate flowcharts from your Mermaid-format text files, and the `git` commands that will preserve all the Markdown and Mermaid text files you create. In any case, once the operating system installation process is complete your virtual machine will reboot, and you'll then be able to log into it using the console window that VirtualBox will present. ## Configuring your virtual machine ### Enabling SSH logins Your first order of business is to enable the ability to log into your virtual machine via SSH using PuTTY, rather than via VirtualBox's console window, so that you can copy and paste commands instead of retyping them. Log into your virtual machine as root via VirtualBox's console window, and type the following commands (granting permission to upgrade/install whenever asked, and replacing `exit` with `reboot` if `apt-get dist-upgrade` upgraded the kernel): ```` apt-get update apt-get dist-upgrade apt-get install openssh-server echo 'PermitRootLogin yes' > /etc/ssh/sshd_config.d/99-local.conf systemctl restart ssh exit ```` Congratulations! You can now log into your virtual machine via SSH using PuTTY^[You'll need to click "Accept" on an alert regarding the "host key" being unknown the first time you do this, but that's normal.] rather than via its console, which means you can now simply copy (Ctrl-c) and paste (Ctrl-Shift-v) commands from this tutorial into your virtual machine's command line. ### Activating your shared folders Your second order of business is to activate the folders that you shared with your virtual machine from Windows; by doing all of your creative work in these shared folders, Pandoc and Mermaid (running on your virtual machine) will be able to access everything you edit in Notepad++ (running on Windows), and you'll be able to view all of their output in Windows. Start by executing the following via VirtualBox's console menu, which loads a virtual CD-ROM that can teach your virtual machine how to access its shared folders: 1. Devices → 2. Insert Guest Additions CD image... Continue by issuing the following commands as root on your virtual machine (as before, granting permission to install whenever asked): ```` apt-get install build-essential dkms mount /media/cdrom0 cd /media/cdrom0/ sh ./VBoxLinuxAdditions.run mkdir -p /mnt/Downloads echo "Downloads /mnt/Downloads vboxsf defaults,\ uid=1000,gid=1000,dmode=755,fmode=755,rw 0 0" >> /etc/fstab mkdir -p /mnt/Work echo "Work /mnt/Work vboxsf defaults,\ uid=1000,gid=1000,dmode=755,fmode=755,rw 0 0" >> /etc/fstab shutdown -h now ```` At this point your virtual machine will be shut down. Back in the VirtualBox menu, issue the following two commands: 1. Machine → Settings... → Storage → VBoxGuestAdditions.iso → Remove Attachment → Remove → OK 2. Machine → Start → Normal Start ### Adding your applications Your third order of business is to add to your virtual machine all the applications you'll actually use on a daily basis (e.g. Pandoc and Mermaid), plus some extra applications that might prove handy in specific circumstances. #### Pandoc Issue the following as root: ```` apt-get install zip apt-get install vim select-editor # pick /bin/nano update-alternatives --set editor /bin/nano apt-get install texlive-full apt-get clean apt-get install dos2unix apt-get install librsvg2-bin apt-get install curl curl -fsSL \ https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | \ gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg NODE_MAJOR=18 echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] \ https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | \ tee /etc/apt/sources.list.d/nodesource.list apt-get update apt-get install nodejs npm apt-get clean wget https://github.com/jgm/pandoc/releases/\ download/3.1.11/pandoc-3.1.11-linux-amd64.tar.gz tar xvzf pandoc-3.1.11-linux-amd64.tar.gz \ --strip-components 1 -C /usr/local/ rm pandoc-3.1.11-linux-amd64.tar.gz wget https://github.com/lierdakil/pandoc-crossref/releases/\ download/v0.3.17.0b/pandoc-crossref-Linux.tar.xz xz -dc pandoc-crossref-Linux.tar.xz | tar x mv pandoc-crossref /usr/local/bin/ gzip pandoc-crossref.1 mv pandoc-crossref.1.gz /usr/local/share/man/man1/ rm pandoc-crossref-Linux.tar.xz exit ```` #### Mermaid Issue the following in your ordinary user account (***not*** as root): ```` select-editor # pick /bin/nano npm install @mermaid-js/mermaid-cli mkdir -p .local cd .local/ ln -s ../node_modules/.bin bin exit ```` ### Enhancing Pandoc Your final order of business is to expand Pandoc a bit by equipping it with another good citation style^[Specifically the "ieee.csl" style, which of the common citation styles that don't commandeer footnotes is the least intrusive to the reader; to select this style just add the line `csl: ieee.csl` to your Markdown file's Pandoc metadata block.], telling it how you want cross-references labeled, and giving it a directory for templates. Issue the following in your ordinary user account: ```` mkdir -p .local/share/pandoc/csl wget -P .local/share/pandoc/csl \ https://raw.githubusercontent.com/citation-style-language/\ styles/983568850741d4cb7a5be102a7643e662f50b286/ieee.csl mkdir -p .pandoc-crossref cat <<'EOF' >.pandoc-crossref/config.yaml secPrefix: - section - sections figPrefix: - figure - figures tblPrefix: - table - tables lstPrefix: - listing - listings eqnPrefix: - equation - equations EOF mkdir -p .local/share/pandoc/templates exit ```` ## Starting and stopping your virtual machine Assuming you're still comfortable logging in via SSH rather than the console, [@tbl:virtualbox] summarizes how to start and stop your virtual machine. **Action** | **Command** :----------|:-------------------------------- Start | Machine → Start → Headless Start Stop | Machine → Stop → ACPI Shutdown : VirtualBox start/stop commands {#tbl:virtualbox} ## Using your virtual machine All of the following must be done in your ordinary user account, *not* as root. ### Pandoc for documents #### Creating a beautiful PDF Here's the simplest possible command to typeset a beautiful new PDF file (to be named "out.pdf") from a Markdown text file (in this case named "doc.txt"): ```` pandoc -f markdown -o out.pdf doc.txt ```` I strongly advise *always* adding `--shift-heading-level-by=-1` to the above command, and then adopting the habit of only having one level-one heading in your document, on its first line; this way, that first and only level-one heading is treated as your document's actual title, all following level-two headings are typeset as level-one headings, etc. There are a few other Pandoc features you could enable: 1. Add `-C` if you'd like to use Pandoc's citation and bibliography features. 2. Before any `-C`, you can add `-N -F pandoc-crossref` if you'd like your document's headings automatically numbered, along with gaining the ability to easily reference those headings *with* their current numbers.^[Note that I said "before any `-C`"; Pandoc's cross-reference processing and citation processing each function as filters that are applied in the order they're given on the command line, and if the citation processor sees unprocessed cross-references it will mistakenly believe those unprocessed cross-references are just broken citations.] 3. Add `--toc` to automatically generate and include a table of contents. Pulling all this together, if you wanted to enable every optional feature I just mentioned, plus the one setting I advised always making, then your Pandoc command would be this: ```` pandoc --shift-heading-level-by=-1 --toc \ -N -F pandoc-crossref -C -f markdown -o out.pdf doc.txt ```` In fact, the above command is exactly what was used to typeset this tutorial. #### Exporting to Google Docs To create a Google Doc from your Markdown text file, simply change the output file's extension from `.pdf` to `.docx` in your Pandoc command; that will cause the output file to have Microsoft Word format, which Google Docs will accept as an upload. If your Pandoc command requested either a table of contents or citation processing, then you might improve the Google Docs import by, just prior to uploading, opening your new `.docx` file in Word, answering "Yes" if asked to update fields, and then saving. Here are a few tips for writing Markdown that will eventually become a Google Doc: * Avoid nested blockquotes (i.e., indented quoted paragraphs within indented quoted paragraphs). * If you're using `pandoc-crossref` to cross-reference figures and tables, then give *all* your figures and tables labels --- not just the specific ones you actually cross-reference. ### Mermaid for flowcharts Mermaid lets you create attractive diagrams from simple and human-readable text files; basically, it does for a document's flowcharts what Markdown does for a document's words. The Mermaid input file shown in [@lst:fc], for which the command in [@lst:fc-mmdc] generated the output shown below, demonstrates all of the flowchart node types along with the most useful link types. ```{#lst:fc caption="Mermaid flowchart demonstration input"} flowchart TB A --> B[rectangle] B ---|std open| C(rounded) C -.-|dot open| D([stadium]) A --> E[[subroutine]] E -->|std arrow| F[(cylinder)] F -.->|dot arrow| G((circle)) A --> H>asymmetric] H <-->|std arrow 2| I{rhombus} I <-.->|dot arrow 2| J{{hexagon}} A --> K[/pgram/] K --x|std cross| L[\pgram alt\] L -.-x|dot cross| M[/tzoid\] A --> N[\tzoid alt/] N x--x|std cross 2| O(((circle 2))) O x-.-x|dot cross 2| P[rectangle] ``` ```{#lst:fc-mmdc caption="Command to generate Mermaid flowchart demonstration output"} mmdc -f -i pandoc-debian-fc.mmd -o pandoc-debian-fc.mmd.pdf ``` ![Mermaid Flowchart Demonstration Output](pandoc-debian-fc.mmd.pdf)  See [`https://mermaid.js.org`](https://mermaid.js.org) to learn additional Mermaid flowchart syntax, as well as the syntax for all of the other diagram types Mermaid can generate (including sequence, class, state, entity relationship, user journey, Gantt, pie, quadrant, requirement, and Git). ## Refinements Now that you have the basics, here are a few extra steps you could take. ### Learning keyboard shortcuts Since this workflow involves cycling through three specific Windows applications, it's perfectly suited to Win-# shortcutting. So pin Notepad++ to your taskbar, right-click your running PuTTY terminal on the taskbar to pin it to your taskbar as well, and finally pin your PDF reader to your taskbar. Then, arrange those three pinned applications on your taskbar in that same order, as the very first pins to the right of the Windows start button (as shown in [@fig:ui]). Once that's done you'll always be able to instantly switch to your text editor with Win-1, your terminal with Win-2, and your PDF reader with Win-3, which in turn (assuming you're using Google Chrome as your PDF reader) means you can accelerate your entire workflow per [@tbl:shortcuts]. **Step** | **Keystroke** | **Purpose** :--------|:--------------|:------------------------------- 1 | `Ctrl-s` | Save your writing 2 | `Win-2` | Switch to your terminal 3 | `Up Arrow` | Recall last Pandoc command 4 | `Enter` | Execute that Pandoc command 5 | `Win-3` | Switch to your PDF reader 6 | `Ctrl-r` | Reload your PDF file 7 | `Ctrl-0/+/-` | Adjust the zoom level 8 | `Mouse Wheel` | Scroll through your PDF file 9 | `Win-1` | Switch back to your text editor : Workflow shortcuts {#tbl:shortcuts} ### Skipping passwords with SSH keys Typing a password every time you log into your virtual machine can become a drag. Switching from passwords to SSH keys lets you skip that. #### Generating your keypair Your first step is to generate your cryptographic keypair. Here's how you do that using the "PuTTYgen" application that comes with PuTTY: 1. Start PuTTYgen. 2. Select "EdDSA" as the type of key to generate (at present leave the associated "curve" at its default of "Ed25519" for compatibility). 3. Click "Generate" and follow the subsequent instructions regarding randomly moving the pointer until your keypair has finally been generated. 4. This is optional, but I think it makes sense to change the "Key comment" from "eddsa-key-[date]" to "eddsa-key-[date]-virtualbox" just to make its purpose unmistakable later on; either way, assuming you'll only be using this keypair to log into the virtual machine you just created, don't put anything in either the "Key passphrase" field or the following "Confirm" field. 5. Click "Save private key," making your key's filename the same as its "Key comment" to avoid confusion later on.^[PuTTYgen will automatically give this filename PuTTY's preferred `.ppk` filename extension, so don't actually type that extension when saving your key.] #### Distributing your public key Next, you need to copy the public key from this keypair to your virtual machine, so that its associated private key can validate you instead of your typed-in password validating you. To accomplish this, issue the following commands in your virtual machine twice: once while logged in as root, and once while logged into your ordinary user account. Where you see "[pasted public key]" in the following commands you should paste everything contained in the "Public key for pasting into OpenSSH authorized_keys" field for your keypair from your PuTTYgen window.^[There's no harm done if you accidentally close the PuTTYgen window for your newly-generated keypair before copying and pasting its public key field; since the public key is recoverable from the material saved in the file for its associated private key, all you need to do is load back into PuTTYgen your .ppk private key file and you'll see its public key again.] ```` mkdir -p -m 700 ~/.ssh echo '[pasted public key]' >> ~/.ssh/authorized_keys exit ```` #### Telling PuTTY to use your private key Finally, back in PuTTY itself, for each of your saved sessions load and then re-save that session after making the following simple change: 1. Connection → SSH → Auth → Credentials 2. Choose your ".ppk" file as the "Private key file for authentication" ### Using Git for backups and version control #### Installing Git itself Simply issue as root: `apt-get install git` #### Installing Git's LFS extension The following steps install a Git extension called "LFS," which gives you the option of telling repository hosting services that certain types of files within your Git repository (particularly large binary files) should be handled in a more efficient way behind the scenes. In the case of Markdown authors, directing right from a repository's beginning that any PNG, JPG, and PDF files be handled via LFS should help it maintain great performance even after a lifetime of heavy use. Issue as root: ```` wget https://github.com/git-lfs/git-lfs/releases/download/\ v3.4.1/git-lfs-linux-amd64-v3.4.1.tar.gz tar xvzf git-lfs-linux-amd64-v3.4.1.tar.gz rm git-lfs-linux-amd64-v3.4.1.tar.gz cd git-lfs-3.4.1/ ./install.sh chown -R root:root man gzip man/man1/*.1 gzip man/man5/*.5 gzip man/man7/*.7 mkdir -p /usr/local/man/man1 cp man/man1/*.1.gz /usr/local/man/man1/ mkdir -p /usr/local/man/man5 cp man/man5/*.5.gz /usr/local/man/man5/ mkdir -p /usr/local/man/man7 cp man/man7/*.7.gz /usr/local/man/man7/ cd .. rm -rf git-lfs-3.4.1/ exit ```` #### Personalizing Git Issue the following in your ordinary user account, replacing [name] and [address] with however you'd like your commits logged. ```` git config --global user.name "[name]" git config --global user.email "[address]" git config --global pull.rebase false git lfs install git config --global core.filemode false ```` In case you were curious, the above "core.filemode" setting is helpful because you'll presumably be cloning your repository to a working directory in one of your shared Windows folders; since Windows filesystems don't preserve UNIX filemodes, Git might otherwise mistakenly believe those filemodes were intentionally changed. #### Selecting a Git host Next, sign up for a free account with a Git hosting service such as [`https://github.com`](https://github.com). You can then follow that service's instructions to: 1. Create a private Git repository for your writing. 2. Configure a suitable form of authentication between your virtual machine and your hosted Git account (one popular choice being SSH keypairs). 3. "Clone" your new repository to the computer you're using, via a command from your virtual machine. 4. Declare any filename extensions you want handled via LFS. #### Good practices * Issue your Git commands from the command line of your virtual machine's ordinary user account. * Clone your repository to a working directory on one of your virtual machine's shared folders, so that you can edit its files with Notepad++. * Don't commit Pandoc or Mermaid outputs --- only their inputs. ### Updating Mermaid Of all the applications now installed on your virtual machine, Mermaid is unique in that you can update it to later versions entirely from the command line of your ordinary user account. This convenience is fortunate, since given GitHub's early 2022 enablement of Mermaid syntax across all its discussion forums, Mermaid's development is likely to accelerate. So, here's how you can update Mermaid while logged into your ordinary user account: ```` npm outdated npx npm-check-updates -u npm install ```` ## Unicode reference [@Tbl:unicode] summarizes the supported printable characters from the following code charts: Latin-1 Supplement (`00A-00F`), Latin Extended-A (`010-017`), Latin Extended-B (`01C-023`), Latin Extended Additional (`1E0-1E2`), General Punctuation (`201-204`), Currency Symbols (`20A-20B`), and Arrows (`219`). If you'd like to learn more about a character you don't recognize, then go to [`https://www.unicode.org/charts/`](https://www.unicode.org/charts/) and click its code chart name. **`   `** |**`0`**|**`1`**|**`2`**|**`3`**|**`4`**|**`5`**|**`6`**|**`7`**|**`8`**|**`9`**|**`A`**|**`B`**|**`C`**|**`D`**|**`E`**|**`F`** :---------|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----: **`00A`** | | ¡ | ¢ | £ | ¤ | ¥ | ¦ | § | ¨ | © | ª | « | ¬ | | ® | ¯ **`00B`** | ° | ± | ² | ³ | ´ | µ | ¶ | · | ¸ | ¹ | º | » | ¼ | ½ | ¾ | ¿ **`00C`** | À | Á |  | à | Ä | Å | Æ | Ç | È | É | Ê | Ë | Ì | Í | Î | Ï **`00D`** | Ð | Ñ | Ò | Ó | Ô | Õ | Ö | × | Ø | Ù | Ú | Û | Ü | Ý | Þ | ß **`00E`** | à | á | â | ã | ä | å | æ | ç | è | é | ê | ë | ì | í | î | ï **`00F`** | ð | ñ | ò | ó | ô | õ | ö | ÷ | ø | ù | ú | û | ü | ý | þ | ÿ **`010`** | Ā | ā | Ă | ă | Ą | ą | Ć | ć | Ĉ | ĉ | Ċ | ċ | Č | č | Ď | ď **`011`** | Đ | đ | Ē | ē | Ĕ | ĕ | Ė | ė | Ę | ę | Ě | ě | Ĝ | ĝ | Ğ | ğ **`012`** | Ġ | ġ | Ģ | ģ | Ĥ | ĥ | | | Ĩ | ĩ | Ī | ī | Ĭ | ĭ | Į | į **`013`** | İ | ı | | | Ĵ | ĵ | Ķ | ķ | | Ĺ | ĺ | Ļ | ļ | Ľ | ľ | **`014`** | | Ł | ł | Ń | ń | Ņ | ņ | Ň | ň | | Ŋ | ŋ | Ō | ō | Ŏ | ŏ **`015`** | Ő | ő | Œ | œ | Ŕ | ŕ | Ŗ | ŗ | Ř | ř | Ś | ś | Ŝ | ŝ | Ş | ş **`016`** | Š | š | Ţ | ţ | Ť | ť | | | Ũ | ũ | Ū | ū | Ŭ | ŭ | Ů | ů **`017`** | Ű | ű | Ų | ų | Ŵ | ŵ | Ŷ | ŷ | Ÿ | Ź | ź | Ż | ż | Ž | ž | **`01C`** | | | | | | | | | | | | | | Ǎ | ǎ | Ǐ **`01D`** | ǐ | Ǒ | ǒ | Ǔ | ǔ | | | | | | | | | | | **`01E`** | | | | ǣ | | | Ǧ | ǧ | | | Ǫ | ǫ | | | | **`01F`** | ǰ | | | | Ǵ | ǵ | | | | | | | | | | **`021`** | | | | | | | | | Ș | ș | Ț | ț | | | | **`023`** | | | | ȳ | | | | ȷ | | | | | | | | **`1E0`** | | | | ḃ | | | | | | | | | | | | **`1E2`** | | ḡ | | | | | | | | | | | | | | **`201`** | ‐ | | | – | | | ‖ | | ‘ | ’ | ‚ | | “ | ” | „ | **`202`** | † | ‡ | • | | | | | | | | | | | | | **`203`** | ‰ | | | | | | | | | ‹ | › | | | ‽ | | **`204`** | | | | | ⁄ | | | | | | | | | | | **`20A`** | | ₡ | | | ₤ | | ₦ | | | ₩ | | ₫ | € | | | **`20B`** | | ₱ | | | | | | | | | | | | | | **`219`** | ← | ↑ | → | ↓ | | | | | | | | | | | | : Select Unicode characters {#tbl:unicode} ## Markdown reference ### Inline syntax **Text** | **Result** --------:|:---------- `*italic*` | *italic* `**bold**` | **bold** `***italic bold***` | ***italic bold*** `` `code` `` | `code` `~~strikeout~~` | ~~strikeout~~ `~sub~script` | ~sub~script `^super^script` | ^super^script `'single quotes'` | 'single quotes' `"double quotes"` | "double quotes" `en--dash` | en--dash `em---dash` | em---dash `$c=\sqrt{a^2+b^2}$` | $c=\sqrt{a^2+b^2}$ `foot^[note]` | foot^[note] : Basic inline formatting {#tbl:inline} **Text** | **Result** --------:|:---------- `[@Sec:headings]` | [@Sec:headings] `[@sec:headings]` | [@sec:headings] `[@fig:ui]` | [@fig:ui] `[@tbl:veg]` | [@tbl:veg] `[@lst:codedemo]` | [@lst:codedemo] `[@eq:ra;@eq:ma]` | [@eq:ra;@eq:ma] : Cross-reference formatting {#tbl:crossref} **Text** | **Result** --------:|:---------- `@PCM2022` | @PCM2022 `@WatsonCrick1953 [p. 737]` | @WatsonCrick1953 [p. 737] `[@Watson2020, pp. 2-3]` | [@Watson2020, pp. 2-3] : Default citation formatting {#tbl:citations} **Text** **Result** ---------------------------------------- ---------------------------------- `` [`http://hp.com`](http://hp.com) `` [`http://hp.com`](http://hp.com) : URL formatting {#tbl:url} ### Headings {#sec:headings} The heading of the subsection you're reading now was typed as follows, with an optional `#sec` label for the sake of cross-referencing from [@tbl:crossref]: ```` ### Headings {#sec:headings} ```` ### Ordinary lists **If you type this**: ```` 1. First step * One consideration * Another consideration 2. Second step ```` **You get this**: 1. First step * One consideration * Another consideration 2. Second step ### Definition lists **If you type this**: ```` Term 1 : This is an explanation of "Term 1." Term 2 : This is an explanation of "Term 2." ```` **You get this**: Term 1 : This is an explanation of "Term 1." Term 2 : This is an explanation of "Term 2." ### Example lists **If you type this**: ```` (@) A first example Any amount of material can be placed here. Sequential numbering of the examples won't be disturbed. Ever. (@) A second example (@good) A third example As (@good) illustrates, labels facilitate cross-referencing. ```` **You get this**: (@) A first example Any amount of material can be placed here. Sequential numbering of the examples won't be disturbed. Ever. (@) A second example (@good) A third example As (@good) illustrates, labels facilitate cross-referencing. ### Blockquotes **If you type this**: ```` > Creating blockquotes is easy, and manual\ line breaks can\ be very useful if you're quoting poetry. > >> You can also nest blockquotes. ```` **You get this**: > Creating blockquotes is easy, and manual\ line breaks can\ be very useful if you're quoting poetry. > >> You can also nest blockquotes. ### Figures Here's the Markdown line near the beginning of this tutorial which added [@fig:ui], gave it its caption, gave it a label for later cross-referencing, and specified how much of the available page width it should be scaled to use: ```` ![Your Screen](pandoc-debian-ui.png){#fig:ui width=100%} ```` In general, use PDF for vector graphics (including Mermaid charts), JPG for photographs, and PNG for everything else (including user interface screenshots). ### Tables Pandoc offers several methods for defining tables. Here's a simple example of one of the simpler methods, which includes both an optional caption and an optional label for later cross-referencing. **If you type this, you get [@tbl:veg]**. ```` **veg** | **price** -------:|:--------- garlic | 1.12 kale | 9.63 carrot | 4.27 : A simple table example {#tbl:veg} ```` **veg** | **price** -------:|:--------- garlic | 1.12 kale | 9.63 carrot | 4.27 : A simple table example {#tbl:veg} ### Code listings #### Plain An easy way to present computer code (or anything else you want typeset verbatim in a monospaced font) is to simply bracket it with lines of backticks. For example: ```````` ```` Code line 1 Code line 2 Code line 3 Code line 4 ```` ```````` #### Fancy The fancy way to present computer code, which also provides captioning and cross-referencing, is instead something like the following. When typeset, it yields [@lst:codedemo]. ```` ```{#lst:codedemo caption="Demo of code block crossref/caption"} main :: IO () main = putStrLn "Code block crossref/caption demo" ``` ```` ```{#lst:codedemo caption="Demo of code block crossref/caption"} main :: IO () main = putStrLn "Code block crossref/caption demo" ``` ### Equations If you bracket an equation with two dollar signs on each side, instead of just one dollar sign on each side, then your equation will be typeset in display format instead of inline format. In the following two examples you'll also see an optional `#eq` label immediately after the typed-in equation, for the sake of our cross-referencing examples in [@tbl:crossref]. **If you type this**: ```` $$\frac{1}{\Bigl(\sqrt{\phi \sqrt{5}}-\phi\Bigr) e^{\frac25 \pi}} = 1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}} {1+\frac{e^{-8\pi}} {1+\ldots} } } }$$ {#eq:ra} $$\begin{aligned} \nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} & = \frac{4\pi}{c}\vec{\mathbf{j}} \\ \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\ \nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\ \nabla \cdot \vec{\mathbf{B}} & = 0 \end{aligned}$$ {#eq:ma} ```` **You get this**: $$\frac{1}{\Bigl(\sqrt{\phi \sqrt{5}}-\phi\Bigr) e^{\frac25 \pi}} = 1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}} {1+\frac{e^{-8\pi}} {1+\ldots} } } }$$ {#eq:ra} $$\begin{aligned} \nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} & = \frac{4\pi}{c}\vec{\mathbf{j}} \\ \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\ \nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\ \nabla \cdot \vec{\mathbf{B}} & = 0 \end{aligned}$$ {#eq:ma} ### Metadata blocks Please consider the first 18 lines of this tutorial's Markdown file: ```` # Technical Writing on Windows 10/11 --- author: - Russell D. Brunelle date: 'January 1, 2024' subtitle: | via a state-of-the-art open-source toolchain abstract: | This tutorial teaches you to create beautiful PDF documents from simple text files. Using Notepad++ you write Markdown that's backed up via Git, Pandoc typesets your Markdown via LaTeX while adding any flowcharts written in Mermaid, and all of this runs (without needing internet access) via VirtualBox on a virtual Debian Linux machine that's accessed via PuTTY. ... ## Our goal ```` Since the Pandoc command that converted this tutorial's Markdown file to a PDF file included a `--shift-heading-level-by=-1` option, the `# Technical Writing on Windows 10/11` line above becomes this document's title rather than a top-level section heading, and the `## Our goal` line becomes a top-level section heading rather than a second-level section heading. In the metadata block between those two lines, one could: * Remove any definitions (author, date, subtitle, or abstract) that aren't needed, or even remove the entire block if none of them is needed. * Add co-authors by adding more `- [name]` lines to the author definition. * Add, on a line of its own, the definition `csl: ieee.csl` if you'd like to switch from Pandoc's default citation style (*Chicago Manual of Style* "author-date") to the IEEE citation style. ### Bibliographic blocks Here is the bibliographic block that was typed into this tutorial's Markdown file, for the sake of the citation demonstrations in [@tbl:citations]. ```` --- references: - id: PCM2022 author: - family: Proulx given: Mike - family: Conroy given: Emma - family: McNair given: Corey title: "Cancel culture is loud, but for most brands it's noise" publisher: Forrester Research, Inc. issued: - year: 2022 month: 1 day: 10 type: report - id: WatsonCrick1953 author: - family: Watson given: James Dewey - family: Crick given: Francis Harry Compton title: 'Molecular structure of nucleic acids' container-title: Nature issued: - year: 1953 month: 4 day: 25 volume: 171 issue: 4356 page: 737-738 DOI: 10.1038/171737a0 type: article-journal - id: Watson2020 author: - family: Watson given: Erin title: '3 things to remember to avoid being cancelled' issued: - year: 2020 month: 2 URL: https://banfield.agency accessed: - year: 2022 month: 5 day: 7 type: webpage ... ```` --- references: - id: PCM2022 author: - family: Proulx given: Mike - family: Conroy given: Emma - family: McNair given: Corey title: "Cancel culture is loud, but for most brands it's noise" publisher: Forrester Research, Inc. issued: - year: 2022 month: 1 day: 10 type: report - id: WatsonCrick1953 author: - family: Watson given: James Dewey - family: Crick given: Francis Harry Compton title: 'Molecular structure of nucleic acids' container-title: Nature issued: - year: 1953 month: 4 day: 25 volume: 171 issue: 4356 page: 737-738 DOI: 10.1038/171737a0 type: article-journal - id: Watson2020 author: - family: Watson given: Erin title: '3 things to remember to avoid being cancelled' issued: - year: 2020 month: 2 URL: https://banfield.agency accessed: - year: 2022 month: 5 day: 7 type: webpage ... ### Everything else We haven't covered absolutely everything, but the following will: * [`https://pandoc.org`](https://pandoc.org) * **For Pandoc's Markdown extensions**:\ Documentation → User's Guide → Pandoc's Markdown * **For Pandoc's citation features**:\ Documentation → User's Guide → Citations * [`https://lierdakil.github.io/pandoc-crossref/`](https://lierdakil.github.io/pandoc-crossref/) ## The auto-generated bibliography for our examples