= 📖 Steadfast Self-Hosting

This is an awesome book about self hosting with code to help you get started.

== Directory structure

|===
|path |description

|`book/` |sources for the book
|`mario/` |sources for mario provisioning tool
|`pelican/` |sources for https://selfhostbook.com/
|===

== Book formats

<<How to build the book,Build your own>>, or https://github.com/meonkeys/shb-review/releases/[Download PDF, HTML, and EPUB versions here].

|===
|version |device |quality

|EPUB |calibre e-book viewer |good
|EPUB |Kobo e-reader |ok
|EPUB |FBReader |bad
|HTML |Firefox web browser |good
|screen PDF |Firefox web browser |good
|screen PDF |evince PDF viewer |good
|print PDF |evince PDF viewer |good
|print PDF |Firefox web browser |good
|print PDF |ink & paper |TBD
|===

== Feedback

Please send me feedback!

* What are your first impressions? Cover, table of contents, font, style, page size, book length, etc.
* Any/all factual, spelling, grammatical, and structural errors.
* Overall manuscript critique, comprehensive or line edits, copy-editing, proofreading.
* Does it make sense what I'm trying to convey and how?
* Consistency of voice, level of detail, narrative flow.
* Anywhere a diagram or photo would significantly help to illustrate a point.
* Any sections that should be rewritten, rethought, or removed.
* Is there a relevant and useful technology that isn't mentioned and should be?
* Test out mario on your own hardware/VM. Does it work for you as advertised?
* Is this book, this code, these ideas something you actually, personally want/read/use?
* Is this something you'd recommend to others?
* What would you expect to pay for a print copy?
* What would you expect to pay for a digital copy?
* Any feedback on the https://selfhostbook.com[book website]?

== Issues

Here's a quick summary of the stuff I'm aware of and working on.
IDs start with `am` to avoid conflicts with IDs that might be generated by some other issue tracker, should I choose one.

|===
|ID |Description |Status |Resolution Details

|am39 |test all links and references in all output formats |OPEN |
|am43 |port to future home (re-do this Readme) |OPEN |
|am44 |re-test mario start to finish |OPEN |
|am46 |make _Services_ map 1:1 with mario: add dyndns, mail, Traefik |OPEN |
|am48 |use service nicknames consistently: e.g. `media.example.com` |OPEN |
|am49 |improve FOSS "`profit`" argument |OPEN |
|am55 |improve htmlproofer |OPEN |
|am57 |professional editing: focus on structure & style |IN PROGRESS |tech review!
|am59 |port `book/build.sh` to Windows |OPEN |
|am60 |port `mario/ansible/provision.sh` to macOS |OPEN |
|am61 |port `mario/ansible/provision.sh` to Windows |OPEN |
|===

== How to build the book

Run `./book/build.sh` to generate your own typeset outputs.

This needs to be ported and tested to other operating systems besides Linux.
See am58 and am59, above.

== Copyright and license

This pre-publication secret manuscript of _Steadfast Self-Hosting: Rapid-Rise Personal Cloud_ is copyright (C)2024 Adam Monsen.
All rights reserved.
Creative Commons licensing does not (yet!) apply.

== Editing stages reference

(from https://www.ingramspark.com/how-to-self-publish-a-book, except the Tech Review section)

=== Manuscript Critique

This is a high-level examination of your manuscript.
It looks at things like narrative voice, plot, and character development.
With this type of critique, editors give feedback on items that will help improve your overall story.

=== Comprehensive Edit / Line Edit

A comprehensive edit addresses structural issues (similar to a manuscript critique), but it also involves a line edit, which looks closely at writing style and language.
With a line edit, an editor focuses on the use of language to communicate your story to a reader.

=== Tech review

Specific to nonfiction technical writing.
Includes reviewing and running code in a text.

https://fadamakis.com/becoming-a-book-technical-reviewer-b0f2fd55f307 is a good introduction to technical reviewing.

Changes in this repository related to tech review begin at the tag `start-tech-review`.

=== Copyedit

A copyedit is often confused with a line edit, but they're very different steps in the editing process.
A copyedit reviews technical flaws--issues with spelling, grammar, and punctuation--and looks for internal inconsistencies throughout the text.

=== Proofread

This is the final step in the editing process. A proofreader examines the final copy of the manuscript (usually after typesetting) for any awkward page breaks, and he or she might perform some light copyediting.

== Style guide

* pay attention to and follow the existing style
** standardize whenever possible and formalize conventions here
* images
** center most and constrain to 80% wide
* exclude optional slashes at ends of hyperlinks
* capitalize product/project names in prose as they appear in upstream's branding/docs
* capitalize only the first letter of the first word of sections/headers
** except: follow styling of proper nouns, acronyms, etc.
* define jargon and acronym twice:
** at first appearance, immediately following the term, in parentheses or locale-appropriate delimiters
** in the glossary
* footnotes
** don't use footnotes
* links
** include links next to or very near context, but try to avoid breaking the flow of text
** always include typed-out URL, never link text directly
*** this is to ensure consistent appearance across print and electronic versions
** exclude URL scheme from http(s) links
*** this is handled automatically by asciidoc option `hide-uri-scheme`
*** `https` is a safe guess/default (and hopefully people insist on `https` client-side!)
** if a link works without `www.` at the beginning of the domain name, omit it
*** this is bit of a risk: we're prioritizing shorter links in favor of more reliable links (some websites redirect, adding back `www.`)
** if a link works without a SEO slug, omit it
*** example w/slug: `+https://reddit.com/r/BorgBackup/comments/v3bwfg/why_should_i_switch_from_restic_to_borg/+`
*** example w/o slug: `+https://reddit.com/r/BorgBackup/comments/v3bwfg/+`
*** shorter is better, canonical/permalink is best (if you are forced to choose)
** use more readable version for cross references whenever possible
*** no: `+<<_more_about_foss>>+`
*** yes: `+<<More about FOSS>>+`
* use "`command line`" to refer to a Linux text-based interactive user interface
* use https://en.wikipedia.org/wiki/Serial_comma[Oxford commas]
* use https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[one sentence] https://sive.rs/1s[per line]
* shell scripts
** prefer long form for command line flags, e.g. `--attribute` instead of `-a`
* release versioning
** use semver-like major, minor, patch version numbers
* source control
** commit early and often
** group logically related changes into single commits
*** consider future maintainers may wish to `git revert`: try to make that easy for them
** group a series of related changes in a branch
** squashing is OK
** before submitting patches:
*** ensure build passes
** commit log messages
*** the first line of a commit log message is very important: say precisely *what* change you made, save the *why* for the rest
*** use infinitive verb forms, e.g. "`add -q quiet option`"
*** don't wrap body text
*** see also:
**** https://mifosforge.jira.com/wiki/spaces/MIFOS/pages/4456742/Commit+Log+Guide
**** https://lore.kernel.org/git/7vr4waoics.fsf@alter.siamese.dyndns.org/
**** https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
** ChangeLog
*** one entry per release
*** summarize major changes since last release
*** use infinitve forms for "`xyz happened`" statements
* use `shb` namespace for document attributes
** short for "`self-hosting book`"
** example: `shb-printPDF`, used when generating a PDF for printing
* include a trailing slash when referencing folders, e.g. `ansible/`
* indexing
** prefer https://docs.asciidoctor.org/asciidoc/latest/sections/user-index/#index-terms[flow index terms over concealed index terms]
** use your gut: index a term when it feels helpful to draw the reader's attention somewhere to read more about the term
** don't worry about indexing every occurence of a particular term
** note: indexes are only generated for PDF outputs
* data is plural, use context for singular (e.g. "piece of data")

== am55: improve htmlproofer

`book/.internal-build.sh` runs `htmlproofer`.
Currently I ignore erorrs with an `|| true` statement.
It would be better to ignore or fix the errors.
This is possible by instrumenting links in the text or adjusting the way htmlproofer is configured and run.

Some recent output:

....
Running 3 checks (Images, Links, Scripts) in steadfast.html on *.html files ...


Checking 173 external links
Checking 94 internal links
Checking internal link hashes in 1 file
Ran on 1 file!


For the Links check, the following failures were found:

* At steadfast.html:6581:

  http://catb.org/jargon/html/G/Good-Thing.html is not an HTTPS link

For the Links > External check, the following failures were found:

* At steadfast.html:650:

  External link https://sunrisedata.io failed (status code 404)

* At steadfast.html:5354:

  External link https://github.com/wallabag/docker#upgrading failed: https://github.com/wallabag/docker exists, but the hash 'upgrading' does not (status code 200)

* At steadfast.html:5713:

  External link https://matrix.to/#/#selfhosted:matrix.org failed: https://matrix.to/ exists, but the hash '/#selfhosted:matrix.org' does not (status code 200)

* At steadfast.html:5988:

  External link https://github.com/strukturag/nextcloud-spreed-signaling#running-with-docker failed: https://github.com/strukturag/nextcloud-spreed-signaling exists, but the hash 'running-with-docker' does not (status code 200)


HTML-Proofer found 5 failures!
....

== Patches welcome

Your contributions are most welcome!
When submitting a patch, please:

. Heed the <<Style guide>>.
. Sign off every commit (`git commit --signoff`).
Sorry, I know this is annoying, but it is important.
It certifies you wrote or otherwise have the right to submit the patch, following https://developercertificate.org[Developer Certificate of Origin, version 1.1].

== Warranty

None.