What is the ideal way of referencing a Linux man page or other offline software documentation in the bibliography?

Questions
1

I’m writing my own personal notes covering system administration using Typst. Even though there are no strict rules regarding citations and bibliography management, I would like to use #bibliography() with the Hayagriva format at the end of the document because I think this is a better alternative to including footnotes and regular hyperlinks in the middle of the text, potentially breaking the flow of reading.

Some of my findings are from Linux man pages (e.g. man less) or PowerShell documentation accessible with the command Get-Help (e.g. Get-Help about_Return). How would an entry of these two examples look like in a Hayagriva file?

I’m thinking of making the bibliography entries so that they include the commands in monospace, looking like this at the end of the document:

[1] “LESS(1)” [Manual] Access: man less
[2] “About return.” [Manual] Access: about_Return

Here’s what I’ve tried so far:

# bibliography.yml
ps-help-about-return:
  type: manual
  title: About return
  url: Get-Help about_Return

man-less:
  type: manual
  title: LESS(1)
  url: man less

// main.typ
Reference to the man page @man-less
Reference to the PowerShell About page @ps-help-about-return

#bibliography("bibliography.yml")

I got the idea of using manual as the type from Stack Exchange TeX. However, this type is not supported by Typst (0.13.1); running typst watch with these entries gives me the error ‘unknown variant manual’.

I’m also not sure whether url is the most suitable field name for storing the command. I’m open to suggestions on this as well.

2

I’m not an expert in bibliography, but personally, I’d set the url property to an online resource that hosts the manual. (i.e. learn.microsoft.com for PowerShell or something like man7.org, linux.die.net or man.archlinux.org for Linux man pages)

This is helpful for users who don’t have the corresponding resources installed on their systems to conveniently get access to the manual page.

3

I actually have considered this alternative and I would probably go ahead with it if this document was intended to be publicly available (for the reason you mentioned at the end).

However, for me, personally (who prefers taking a look at the offline documentation first), it would involve a few additional steps with little gain: finding out what the URL of the online equivalent of the manual page is, and then copying and pasting the URL into the bibliography. In contrast, I would find it easier to type in a command like man less.

4

I think you would use something like note and reference with a custom CSL, as I don’t see built-in ones that support both.

#let bib = ```yaml
ps-help-about-return:
  type: reference
  title: About return
  publisher: Get-Help about_Return
  # note: Get-Help about_Return

man-less:
  type: reference
  title: LESS(1)
  publisher: man less
  # note: man less
```.text

#bibliography(bytes(bib), full: true)

image

1 Like
5

I’ve taken a look at the CSL specification. I find it overwhelming, even after trying to edit an existing CSL style with a visual editor, so I think I’m going to skip on this for now.

I’ll stick with using reference as the type, coupled with the fields title and publisher for the time being. Thank you!

1 Like
6

I haven’t used visual editor, but it is hard to start. I think it’s even harder when you use an existing one that is complex. But after some time it does get easier. At least if you have adequate requirements for a style (unlike GOST R 7.0.5-2008).