Publishing Manual
1 Introduction
1.1 Summary
Please note any "TODO" or "TK" - that means text around it is incomplete or inaccurate, such as missing a citation.
This is my (emsenn's) guide to publishing, which for me means taking a document and distributing it on the Internet, primarily in one place (through several protocols) but usually syndicated in multiple places. In a way, it's a sequel to my Writing ManualTK, which is my guide for taking an idea and turning it into a document.
While I hope it's of use to other people, at the moment, with it being an early draft, it's mostly for my own use.
1.2 License & Editorial Information
This document and the source code it contains are released under the MIT License and maintained at https://git.sr.ht/~emsenn/publishing-manual, where a list of syndications is available.
1.3 Table of Contents
1.4 Using this File
This file contains a bunch of Org-mode stuff; description TK.
2 Preparing a Document
To better explain what a document is, and what "publishing" it means, I think I'm going to first explain how I prepare a document for publication.
2.1 A Document Repository
I keep each document in its own repository (on most of my computers,
under the ~/org/docs/ directory), which contains at a minimum two
files, which make use of two variables:
The two variables are the document's title and slug - the first is
its name as it should be rendered, and the second is the name to be
used in naming files or making links. For example, this document's
title is Publishing Manual and its slug is publishing-manual.
Each repository contains a ./README.md, and the original org-mode
source document, which is at ./[document-slug].org. That's the file
that I'll spend my time in, editing it with EmacsTK. Once I'm ready,
I'll probably export that source document into different formats, and
if it has any source blocks that are tangled (extracted out to their
own files), it'll end up with some more files.
For example, here's an outline of this document's repository:
./
├─ README.md
├─ publishing-manual.org
├─ publishing-manual.html
├─ publishing-manual.tex
├─ build/
├─ demo-repo/
├─ README.md
├─ demo-repo.org
3 Publishing a Document
3.1 Rendering
Rendering is taking the original source document and producing more distributable formats of it, for example taking an essay written in Org-mode and rendering it as an HTML document.
3.1.1 Hugo-compatible Markdown
To create a Hugo-compatible Markdown rendering of a document, I first
open the document in Emacs and export it as Github-flavored Markdown
to a new buffer which I save to the document's directory, as
document-slug.hugo.md.
I then clean up the file, which usually means:
- Replacing the top headline with TOML frontmatter.
3.2 Publishing
3.2.1 emsenn.net
The primary place I publish my non-commissioned writing is on my website, emsenn.net, which is distributed through the HTTP and DAT protocols, and backed up onto the IPFS. (See my contact page for more details.)
To publish a document on my website, I copy the rendered
Hugo-compatible Markdown into my website's repository, under the
/content/docs/ directory.
Then, I rebuild the site with Hugo, and upload it to neocities - the commands look something like:
cp document-slug.hugo.md ~/org/projects/website/content/docs/ cp document-slug.hugo.md ~/org/projects/website/build/content/ cd ~/org/projects/website/build hugo cd public neocities push .
3.3 Syndication
3.3.1 Wordsmith.social
Wordsmith.social is an instance in the Fediverse running the Write Freely platform, and it's where I choose to syndicate my in-progress and general-topic non-commissioned writing.
Syndication on Wordsmith serves mostly to make accessing my content a little easier to people who live on the Fediverse, so I haven't put much effort into making sure my posts there look nice.
I use the writefreely.el script to upload my Org-mode source
documents as posts, by running the command
writefreely-publish-or-update.
3.3.2 LBRY
LBRY is a decentralized? media store where I syndicate PDF renderings of my documents, available in exchange for the platform's cryptocurrency.
To syndicate on LBRY, I open the app and use the menu to Publish a
new PDF, filling out what parts of the form I can. I copy the
description from the document's README.md. So far, I've set
everything to cost $1.