Auction Manual

You need to have the following software installed to be able to use Auction:

GNU Awk

The GNU implementation of Awk is explicitly required - you can check which implementation you have by running awk --version

Emacs

Any version from the last decade should be fine

A POSIX-Compatible Shell

Any version

1. Download

2. Extract the archive

   tar xzf auction.tar.gz

3. The org version of this manual is included with the installation to serve as a reference.

   Navigate to the directory and export it:

   cd auction; ./auction.sh manual.org

   This will generate a manual.html file in the same directory.

This is how documents are exported with Auction: you execute auction.sh with the path to the org file you want to export, and it'll generate an HTML file in the working directory.

The rest of this manual discusses everything there is to know about Auction in detail. But before you proceed you may want to take a moment here and take a look at the manual.org file you just exported to get a feel of things.

The following text effects are supported:

• bold text with *

• italic text with /

• underlined text with _

• strikethrough text with +

• inline code with ~

These use the semantic HTML elements strong/em/ins/del. For inline code a span with the class inline-code is used. Delimiters can be escaped with backslashes, e.g. \* to avoid bold text. The text highlighting algorithm is not completely identical to org: for example in org escaped delimiters can be significant on the right-side of the text they're highlighting. But for the most part things should work the same.

Characters that are syntactically significant in HTML such as <less than< >greater than> symbols, &ampersands& </etcetera> are properly escaped. You can use backticks to avoid this and export text literally, e.g. `<span style="color: red;">I'm red</span>` is exported as I'm red.

Headings can be nested to arbitrary level. Since HTML only provides 6 heading levels, heading levels exceeding this depth are translated to ordered lists. When rendered as a section, heading levels are "promoted" as appropriate. (e.g. the name of this section, Exporter, is rendered with an h1 element, despite it being a second-level heading in the org file using two asterisks.)

Heading Property Blocks

**** Heading Property Blocks
:PROPERTIES:
:ID: violet-heading
:STYLE: color: violet;
:END:

ID links in the format [[id:violet-heading][example]] are translated to internal links such as example. Any other link such as [[https://monospace.games/][example 2]] is exported without change to its link: example 2.

One very small feature; if a link is a mailto: link and the mail address associated with it is the same as the link text, the link element is given the mail class. Here's one example of such a link: test@example.com. The reason for this is that such links are not possible to detect with CSS alone, and you may want to style them differently, e.g. avoiding line breaks in them.

Code blocks (those that begin and end with #+begin_src, #+end_src) are syntax highlighted. Here's the script that does the highlighting:

#! /usr/local/bin/emacs --script

;; Load htmlize
(require 'package)
(package-initialize)
(require 'htmlize)

(let ((target (pop command-line-args-left)))
  (find-file target)
  (kill-whole-line)          ; Delete the first line, which is used to set mode
  (font-lock-fontify-buffer) ; Force fontification, required in batch mode
  (with-current-buffer (htmlize-buffer)
    (princ (buffer-string))))

Any other block is exported literally. This makes it possible to embed markup, styling and scripts directly in your document, as an example here's an SVG:

Unordered lists can be constructed with - and +. Ordered lists can be constructed with 1., 1), A., A). Similar to headings, lists can be nested to arbitrary level. Paragraphs will break out of lists according to their indentation level as appropriate. Definition lists are also supported with the - term :: definition syntax, e.g.:

term

definition

other term

other definition

#+TITLE is exported as the top-level heading of the document. The use of a title is required: it's treated as the root of the section tree for the document.

The #+DATE setting is exported as a time element. It's optional and can occur more than once in the file. Its value should be a timestamp containing both date and time, e.g. <1969-07-20 Sun 20:17>

#+META is for any other information - contents of #+META directives are appended at the end of the document in an HTML comment block.

Since sections represent portions of the document that render as standalone units, they must be capable of being linked to, thus each section must have an ID. If the heading associated with a section does not have an existing ID, one is auto-generated from the section name according to the following algorithm:

1. Get the text up to the first opening parenthesis

2. Replace spaces with dashes and remove non-alphanumerical characters

3. Turn to lowercase

As an example this generates the id "whats-auction" from "What's Auction"

Note that this method does not check whether the generated ID's are unique or not, as it's not possible to infer which heading you may have meant if the ID has been used in a link. You should pay attention to the names of the headings in your document, and assign ID's explicitly if any two share the same name.

The data-bottom-navbar attribute determines the links that appear at the bottom of sections. It can be set to the following values:

none

No links.

next

Links to the next section.

sequential

This section, and all sections that descend from it, link to next section.

children-direct

Links to sections which are direct children.

Note that this is not a class but a custom attribute, hence the data- prefix. Here's an example of how it's used:

**** Example Heading
:PROPERTIES:
:CLASS: terminal-section
:DATA-BOTTOM-NAVBAR: children-direct
:END:

If multiple data-bottom-navbar values apply to a section, the priority order is as follows:

Miscellaneous Behavior

Collapsible Headings

Auction does not produce minified documents. The HTML, CSS and JS files associated with it are intended to be human-readable, and they're included in the output as-is.

A minifier can do adjustments such as getting rid of comments, excess whitespace, and replacing variable names with shorter ones to significantly reduce the size of web documents without altering their behavior. You're highly recommended to use one before publishing the documents you generate with Auction online.

An example minifier is the npm package minify. You can use it as follows:

1. Install npm

2. Install minify

   npm install -g minify

3. Call minify on your output

   minify manual.html > manual-min.html

In the draft version of this document minification results in a ~30% reduction in file size.

If you wish to configure Auction you'll have to edit its source files. But that's not as scary as it may sound, and here I'll describe how to do a few configurations that you're most likely to be interested in.

The source files reside in the internal directory, which has the following contents:

internal
├── base.html
├── style.css
├── script.js
├── export.awk
└── syntax-highlight.el

The style.css file determines the style and appearance of your documents. export.awk and syntax-highlight.el deal with turning org to HTML, script.js deals with interactivity, and base.html is the output template.

The main thing you'll wish to configure will likely be the color palette. This information resides in the following two rulesets in style.css:

body[data-theme="light"] {
  /* Light palette */
  --color-text-main: #1e1e1e;
  --color-text-deemphasized: #6f6f6f;
  --color-text-highlighted: #d00058;
  --color-text-error: #ff2951;
  --color-link-unvisited: #00adff;
  --color-link-visited: #0069c2;
  --color-bg-main: #fff;
  --color-bg-surface-one: #e0e0e0;
  --color-bg-surface-two: #525157;
  --color-bg-surface-three: #d2d1d7;
  --color-accent-one: #1c86ee;
  --color-accent-two: #e5f3fe;
}

body {
  /* Dark palette - default  */
  --color-text-main: #e3e3e3;
  --color-text-deemphasized: #9e9e9e;
  --color-text-highlighted: #e6cd69;
  --color-text-error: #ff2951;
  --color-link-unvisited: #00adff;
  --color-link-visited: #6dcfff;
  --color-bg-main: #1b1b1b;
  --color-bg-surface-one: #313131;
  --color-bg-surface-two: #3b3a40;
  --color-bg-surface-three: #525157;
  --color-accent-one: #1c86ee;
  --color-accent-two: #182631;
}

The first set lists the colors associated with the light theme, and the second the dark theme. To alter the palette of your document just replace the RGB color values listed here and re-export.

You may also be interested in altering the icons used in your document. These are stored in the style.css file as follows:

  background: url("data:image/svg+xml;base64,<base64-encoded-svg-source>");

Find the icon you wish to edit, e.g. header .theme-toggle[data-state="dark"] is the icon of the theme toggle button when dark theme is active, and decode the SVG as follows:

This will produce the SVG source for the icon, e.g.

<svg xmlns='http://www.w3.org/2000/svg' viewBox="0 0 100 100">
  <defs>
    <path id="ray" d="M 50 15 v -10"
          stroke="#ffd700" stroke-width="5" stroke-linecap="round" />
  </defs>
  <circle cx="50" cy="50" r="27.5" fill="#ffd700" />
  <use href="#ray" transform="rotate(0 50 50)" />
  <use href="#ray" transform="rotate(45 50 50)" />
  <use href="#ray" transform="rotate(90 50 50)" />
  <use href="#ray" transform="rotate(135 50 50)" />
  <use href="#ray" transform="rotate(180 50 50)" />
  <use href="#ray" transform="rotate(225 50 50)" />
  <use href="#ray" transform="rotate(270 50 50)" />
  <use href="#ray" transform="rotate(315 50 50)" />
</svg>

Which is rendered as:

Edit this image (I have a blog post on this that you might want to read), and when done base64 encode your image and replace the original string.

Auction represent sections with internal links by default, e.g. manual.html#seo-fix for this section. But internal links are not indexed as distinct pages by search engines. To fix this we want to link to our sections in the form manual/seo-fix instead.

Auction has a backend-agnostic "hosted" mode for this purpose. To use it, build your document with the url option, e.g.

Then open the generated HTML file, and edit it so that the INITIAL_RENDER variable in the script block just below the title is initialized to the string section when the user visits the URL manual/section. In django this can be accomplished by editing just two lines as follows:

1. Add the URL pattern:

   urlpatterns = [
       path("manual/<slug:slug>", TemplateView.as_view(template_name="manual.html")),
   ]
   

2. Move the manual.html to an appropriate template location, and edit INITIAL_RENDER so that it's initialized to the slug captured from the URL:

   <script>
     HOSTURL = "https://www.example.com/manual"
     INITIAL_RENDER = "{{ slug }}"
   </script>
   

In hosted mode Auction does not send a fresh request each time you navigate to a section, instead it detects such links and treats them as if they're internal.

Auction will also detect if a hosted document is not being read from the URL it has been exported with (e.g. a hosted document that has been downloaded by the user) and fall back to the default behavior in such cases.