Txt guides

git-svn-id: file:///srv/svn/repo/kosuzu/trunk@33 eb64cd80-c68d-6f47-b6a3-0ada418499da

.gitignore

@@ -6,4 +6,5 @@
 *~
 *.o
 *.native
-_build
+_build
+*.htm

Makefile

@@ -15,4 +15,11 @@ tgz:
 	tar czvf "logarion-$(shell date -r _build/default/cli/cli.exe "+%y-%m-%d")-$(shell uname -s)-$(shell uname -m)-$(shell git rev-parse --short HEAD).tar.gz" txt readme
 	rm txt
 
+htm:
+	rm -f {3sqd84,hvhhwf,ka4wtj,h1a9tg}.htm
+	txt convert readme.txt -t htm
+	txt convert txt/3sqd84.txt -t htm
+	txt convert txt/hvhhwf.txt -t htm
+	txt convert txt/h1a9tg.txt -t htm
+
 .PHONY: cli

readme.txt

@@ -3,23 +3,17 @@ Title: Logarion
 
 ## Guides
 
-Exploring & pulling texts from Logarion repositories.
-<3sqd84.html>
-
-Creating texts & publishing on the net.
-<hvhhwf.html>
-
+- Exploring & pulling texts from Logarion repositories. <urn:txtid:3sqd84>
+- Creating texts & publishing on the net. <urn:txtid:hvhhwf>
+- Txt uniform resource names <urn:txtid:h1a9tg>
 
 ## Contacts
 
-* Mailing list (anonymous) <https://lists.tildeverse.org/postorius/lists/logarion.lists.tildeverse.org/>
-* <irc://tilde.chat/#logarion>
+- Mailing list (anonymous) <https://lists.tildeverse.org/postorius/lists/logarion.lists.tildeverse.org/> 📧
+- <irc://tilde.chat/#logarion> 💬
 
 
 ## References
 
-### Header format
-<http://git.disroot.org/orbifx/logarion/raw/branch/master/header>
-
-### Source
-<http://git.disroot.org/orbifx/logarion>
+- Source <http://git.disroot.org/orbifx/logarion>
+- Header format <http://git.disroot.org/orbifx/logarion/raw/branch/master/header>

txt/3sqd84.txt

@@ -0,0 +1,10 @@
+ID: 3sqd84
+Date: 2022-11-06T13:01:19Z
+Title: Exploring & pulling texts from Logarion repositories
+Authors: orbifx
+
+Logarion repositories are collections of text files, accompanied by a special index file. These collections can exist on any server and accessed by any transport protocol. Logarion's client currently supports a plethora of protocols, HTTP, FTP, Gopher to name a few examples.
+
+A remote repository can be registered and texts copied locally. To add a new remote run: `txt pull <url>`, where <url> is the address of the remote repository. The program will connect to the server, copy the `index.pck` file and use it to download each text file. It will not redownload previous texts, unless their Date or Date-Edited dates are newer than the previous ones.
+
+The text files are by default downloaded to `.local/share/texts/peers/`. A new directory is created for each peer's unique id and the index & texts are stored in it. Running `txt pull` with no URL, will refetch indices from all previously pulled repositories, and new text files will be downloaded automatically.

txt/h1a9tg.txt

@@ -0,0 +1,16 @@
+ID: h1a9tg
+Date: 2022-11-20T13:28:57Z
+Authors: orbifx <orbifx@orbifx.indy>
+Title: Txt uniform resource names
+
+Logarion texts are transport agnostic. URIs should therefore avoid using URLs and use URNs instead. Some definitions of Uniform Resource:
+- Locator (URL) <http://en.wikipedia.org/wiki/Url>
+- Identifier (URI) <http://en.wikipedia.org/wiki/Uniform_Resource_Identifier>
+- Name (URN) <http://en.wikipedia.org/wiki/Uniform_Resource_Name>
+
+
+Links enclosed in angled brackets <> of the format:
+
+    urn:txtid:abcdef
+
+where `abcdef` is the id of the text are understood by `txt` and handled accordingly. For example when converting to HTML or Gemini, the URNs are converted to relative URLs which browsers can understand.

txt/hvhhwf.txt

@@ -0,0 +1,52 @@
+ID: hvhhwf
+Date: 2022-11-06T13:19:57Z
+Title: Creating texts & publishing on the net
+Authors: orbifx
+
+
+# New
+
+To create new text files, use `txt new "<My title>"` where <my title> is the initial title you wish the text to have. 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, `txt new -i "<My title>"` to have the text editor launched to edit the newly created file.
+
+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: unique string for the repository to published
+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

txt/main.css

@@ -0,0 +1,8 @@
+body{color:#111;background:#faeed6;margin:auto;padding:1ch;max-width:80ch}
+@media(min-resolution:130dpi){body{font-size:1.5em}}
+article>header{margin:auto;padding:1ch}
+dt{float:left;text-align:right;padding-right:1ch;min-width:8ch;opacity:0.4;clear:left}
+:target::before{content:"☞"}
+body>h1{font-family:cursive}
+h1,h2{color:#ff6600}
+h3,h4{color:#333}