source: code/trunk/doc/hvhhwf.txt@ 75

ID: hvhhwf
Date: 2022-11-06T13:19:57Z
Title: Creating texts & publishing on the net
Authors: orbifx
Topics: Logarion

# New

To create new text files, use "txt new". For example:
        txt new "Hello world"
It's important to enclose the title with quotation marks if it contains spaces. The command will return the filename of the new text. The filename starts with a part of the ID and the title of the text. Use the file name to open it with your text editor.

Alternatively add the -i flag to have the text editor launched to edit the newly created file:
        txt new -i "Some title"

Text files will be stored in either:
1. The directory pointed at by txtdir if defined
2. $HOME/.local/share/texts, if directory exists
3. The current working directory, if all else fails

The simplest approach is to put all texts in the local-share directory and override that on occasion with 
$txtdir. For example:
        txtdir=. txt new "Hello world"


# Publish

Texts created with "new" are treated as personal until published. To publish a text, use `txt publish [id]` where [id] is the text of the text to publish. Publication requires a `txt.conf` file which must exist in either:
1. The current working directory
2. $HOME/.config/txt/txt.conf

With the above in place, `txt publish [id]` will add the text file with [id] in the publication-directory and reproduce the `index.pck` in that directory. If Pubdir is not defined in `txt.conf` then the environmental variable `txtpubdir` is used. If that is also undefined, the current working directory is used as a publication directory.

Logarion is protocol agnostic, so publish looks for the existence of directories to copy the files, ready for publication. At the time of writing the three directories are `public_html`, `public_gemini` and `public_gopher`. For each of these directories, `txt publish [id]` will copy the text file, revise the `index.pck` and also convert produce converted files, such .htm for public_html.

## txt.conf keys

Id:
        A random, unique, alphanumeric string for distinguishing the repository (atleast 6 characters of Crockford's Base32 recommended)

Title:
        a human-friendly title

Authors:
        comma seperated list of names and, optionally, addresses

Topics:
        topics the repository aims to cover

Locations:
        list of URIs the repositories can be accessed

Peers:
        list of peer URIs

Pubdir:
        (optional) the directory that contains publication subdirectories


## HTML

There are some special settings for HTML publication:

HTM-style:
        path to a CSS style. It will be inserted in every .htm file. To link to a single CSS consider using `@import`

HTM-header:
        path to a file, inserted in every .htm file, right after the body tag

HTM-footer:
        path to a file, inserted in every .htm file, right before the body tag

HTM-index:
        if defined, determines the filename for the index files. Left undefined, defaults to `index.html`

HTM-feed:
        if defined, this will overrite the feed URI used in HTML files. If left undefined the default `feed.atom` is used