UPDATE-YORICKDOC(1)

✨ update-yorickdoc — the girl who builds your Yorick HTML docs 💅

okay bestie, welcome to update-yorickdoc(1) — it's a Yorick manual page and it's literally the backstage pass to your HTML documentation situation. no cap. 🎀

🌸 SYNOPSIS 🌸

update-yorickdoc [--conf=file] [--auto] [--auto-now] [--from=directory]
[--to=directory] [--xref-dir=directory] [--src-dir=directory]
[--template=file]

💖 DESCRIPTION 💖

so. update-yorickdoc is a wrapper. a little cutesy wrapper around htmldoc.i, which is a Yorick script that goes through Yorick source files, scoops out all the DOCUMENT comments, and turns them into a whole set of HTML files. it's giving ✨documentation era✨.

here's the whole routine, step by step:

1. it merges files from a "source directory" — default is /usr/share/yorick-doc, and you can override that with the --src-dir command-line option.
2. it deletes the target directory — default /usr/share/doc/yorick-doc/html_xref. yeah, it just deletes it. dramatic but necessary 💀
3. and if Yorick is installed, it calls yorick -batch htmldoc.i to compile HTML documentation for all the currently installed functions — whether they come from the main Yorick package or from add-on packages.

update-yorickdoc is designed to be called automatically whenever a Yorick package gets installed or removed. if you want to block that auto-update behaviour, set ENABLE_AUTO to 0 in /etc/yorick-doc. and if you're feeling main character energy, you can also run update-yorickdoc manually — like to build docs from your own custom directories (a user's own ~/Yorick/ directory, for example) or dump them somewhere custom. obsessed. 🦋

it also has a set of default parameters to work with, and those get overwritten in chronological order by, in this exact order:

1. the content of /etc/yorick-doc
2. $HOME/.yorick-doc
3. the command line

🫶 a few files are required for this script to function, bestie. default files ship in the default source directory, and add-on packages are supposed to provide their extra info in that same place. check FILES down below, and also /usr/share/doc/yorick-dev/yorick-policy.gz.

🎀 OPTIONS 🎀

• --auto, -a — this flag is being deprecated by the arrival of triggers in dpkg. on systems where dpkg supports triggers, -a turns update-yorickdoc into a no-op. on older systems, it behaves like -A below. (iykyk 🌈)
• --auto-now, -A — this one is meant to be used only in the postinst script of the yorick-doc package, which is in turn supposed to be triggered every single time a yorick add-on package is installed, upgraded, or removed. and yes, you can make update-yorickdoc a no-op when this flag is set by setting ENABLE_AUTO to 0 in /etc/yorick-doc.
• --conf=file — read configuration from this file. it gets parsed as the option is found on the command line, so it overwrites the options that came before it. order matters, bestie. 💅
• --from=directory1:directory2... — a colon-separated list of directories to scan for Yorick files. default: /usr/share/yorick/i:/usr/share/yorick/i0.
• --purge, -p — only delete /usr/share/doc/yorick-doc/html_xref (or whatever directory you set with --to and --xref-dir, or the equivalent variables in /etc/yorick-doc), and do not rebuild the documentation afterwards. clean slate, no rebuild. 🙈
• --quiet, -q — be quiet, only telling you shortly what update-yorickdoc does. this is the built-in default, but it may have been overridden in a configuration file. so don't be surprised if your quiet girl is suddenly loud.
• --src-dir=directory — the directory containing the .packinfo, .keywords and .aliases files when building the documentation. each of these three types of files gets concatenated in lexicographical order and fed to htmldoc.i using the --packinfo, --keywords, and --aliases options (peep htmldoc.i). default: /usr/share/yorick-doc.
• --template=file — the template file for htmldoc.i. the correct format is detailed in htmldoc.i. default: /usr/share/yorick-doc/template.html.
• --to=directory — the top-level directory of the Yorick HTML hierarchy to update. this sits one level above the directory that will be deleted and/or (re)built. defaults to /usr/share/doc/yorick-doc.
• --verbose, -v — be verbose and output lots of debugging information. the built-in default is to be quiet, just telling you shortly what update-yorickdoc does. pick your vibe. ⭐
• --xref-dir=word — the sub-directory of the "TO" directory where the documentation gets compiled. certain hyperlinks in the documentation will use this value.

💀 warning, fr fr: this should not be set to a directory whose content you value, since this directory will be first erased. like, gone. so choose wisely, bestie.

default: html_xref.

🦋 FILES 🦋

• /etc/yorick-doc — the system-wide configuration for update-yorickdoc. this is the right place to set ENABLE_AUTO=0 in case you don't want Yorick's documentation rebuilt every single time a package of the Yorick suite is installed, upgraded, or removed. another interesting option here is FROM, where you can add things like /usr/local/yorick/i if you maintain a secondary Yorick tree at your site. see the file itself for more details. 👑
• $HOME/.yorick-doc — the user-level equivalent of the file above. it is ignored for the root user.
• /usr/share/yorick-doc/*.packinfo — source for the package index in the documentation.
• /usr/share/yorick-doc/*.keywords — lists of keywords for the index page of the documentation.
• /usr/share/yorick-doc/*.aliases — see htmldoc.i.
• /usr/share/yorick-doc/template.html — template file for htmldoc.i.
• /usr/share/yorick/i/htmldoc.i — the Yorick script that does most of the actual work. the real MVP. 🔥

🌈 SEE ALSO 🌈

• /usr/share/yorick/i/htmldoc.i
• /usr/share/doc/yorick-dev/yorick-policy.gz
• dh_installyorick(1)

💜 AUTHORS 💜

Thibaut Paumard <paumard@users.sourceforge.net> — iconic, no notes.

and that's the whole page, bestie — this one's dated 2008-05-18 and comes to you from the Yorick manual set as update-yorickdoc(1). go build some docs, you absolute legend. 💅✨🎀