#!/usr/bin/python
# -*- coding: utf-8 -*-
"""Volks-Hypertext paper: make vh files browsable on paper.
I’m appropriating a now-withdrawn hack by Ray Gardner, later adapted
by ESR, for purposes of producing paper browsable hypertext corpuses.
It still has a page at .
The Volks-Hypertext File Format
-------------------------------
Quoting from vh.1:> .SH TEXT FILE FORMAT> `Proper format' means:> > 1. References are surrounded by {} or {{}}.> > If the first character of the text file is not a `=', the code also assumes:> > 2. Reference text may not begin with whitespace, single- or double-quote, nor> end with a semicolon.> > 3. Reference targets begin with a `:' at the left margin and are bounded> on the right by another `:' (an optional second `:' may follow that).> > These rules are useful for filtering out false hits from the index.
You can download some files in this format from
and vh itself from the
Ubuntu repositories. A couple of clarifications:
- {reference text} may be broken across lines.
- :definition names: may not.
- {{double braces}} only occur once in the latest of these files and
don’t appear to have any special meaning over single braces. As
explained below, they’re a leftover from an older format that had
two different kinds of "headwords".
### Evolution of the format ###
* Versions up to and including jarg221 have no such markup.
* jarg231-251 uses in place of both :: and {}, but vh may not have
existed yet.
* jarg262-296 uses {} but has no leading :, apparently trusting to
leading indentation to prevent spurious index entries. This is
probably the best-looking version of the format. It explains the
difference:
> In this all-ASCII version, headwords for topic entries are
> distinguished from those for ordinary entries by being followed by
> "::" rather than ":"; similarly, references are surrounded by
> "{{" and "}}" rather than "{" and "}".
* jarg300-jarg447 are in the final vh format.
* jarg447 seems to be the last version available in text format;
there's an HTML version of 4.4.8 on ESR’s site, but no .txt version.
### Benefits and drawbacks of the format relative to HTML ###
`vh` can browse megabytes of text with instant response, even on an
old MS-DOS
Use in print
------------
That format is relatively easy to read if you print it out, too. The
trouble is, following references may require a linear search from the
beginning, if the file isn’t already alphabetized. The Jargon file
*is* already alphabetized, so you can do binary search.
"""