[###style:css-dyntoc]

Ethering


< DRAFT++ >

Table of Contents
1 INTRODUCTION
2 *** BASICS: VOCABULARY & PRINCIPLES
2.1 * Documents (or "pads") are contained in a pod.
2.2 * All pads are accessible as online links
2.3 * You can open documents either in VIEW or EDIT mode.
2.4 * VIEW mode is ... normal websites
2.5 * EDIT mode is ... real-time collaborative writing
2.6 * Editing is trivially simple
2.7 —————
2.8 * Learning basics of computer use will help you use the system more effectively.
2.9 * Your contribution to the pod is essential !
2.10 —————
2.11 * Work with the pod keepers
2.12 * Keep improving
2.13 * Learn & remember basic keyboard shortcuts
3 *** BASICS: USE
3.1 * Don't even try to work on documents on mobile
3.2 * Search for content within the document
3.3 * Learn and use other basic keyboard shortcuts
3.4 * Don't delete content on your own
3.5 * Following positions & moving within pads
3.5.1     → "Ctrl+F"
3.5.2     → "Read Planning!"
3.5.3     → "Line 64"
3.5.4     → "Let's work on protocol-going"
3.5.5     → "Check!"
3.6 * Styling & headering 101
3.6.1     * Just use Etherpad's text styles!
3.6.2     * Make Headers with Bold+Underline.
3.6.3     * ... Indent 4 spaces for Subheaders.
4 *** INTERMEDIATE: E2h SYNTAX
4.1         * Internal links (Intralinks)
4.2         * Auto-generated Table of Contents
4.3         * Images by URL, via upload, or from other Pods
4.4         * Links-on-text
4.5         * Cross-instance links (Cross-links)
4.6         * Adopt Styles from other pads ("-css")
4.7         * Image galleries (from Pods, or local storage)
4.8         * Text-to-Graph (flowcharts, diagrams, networks, etc)
4.9         * Include maps
4.10         * Include content via Date
4.11         * Explanations on text (like this)
4.12         * Transclusion
4.13         * File uploading
5 *** INTERMEDIATE: SYMBOLS & CONVENTIONS)
5.1 Access Levels
5.2 Collaboration & prioretization
5.2.1         "BANGS", "HASHES": Marking tasks & improvement parts
5.2.2         NAME TAGGING: Involving others
5.2.3         SIGNED COMMENTS & INLINE CONVERSATIONS
5.3 Adding content in the right place
5.3.1         "GENERAL NOW-POINT" (for new, unsorted content)
5.3.2         "NOW-POINTS" (current working location)
5.3.3         "NEW-POINTS" or "FORKS" (space for new unsorted content)
5.3.4         "EXPAND HERE"
5.4 Document structure & connections
5.4.1         Header levels
5.4.2         TOC: Table of contents
5.4.3         Making links (to other documents)
5.5 Corrections from Editors
6 *** ADVANCED: MAINTAINER CONCEPTS
6.1 Consider document purpose
6.2 Write Quality Documentation !!
6.3 Keep publishing
6.4 Styling basics
6.5 Marking document state
6.6 Fragment tagging!
6.7 Assisting Editors
6.8 Organize & lead Etherbeamer sessions
6.9 Simple & powerful theming
6.10 Hypothes.is annotation support
7 *** EXPERT: EDITORIAL & COLLABORATIVE CONCEPTS
7.1 Editorial & Domain specific syntax
7.2 Leading reviews
7.3 Leading overviews
7.4 Cleaning up Very Dirty Pads
7.5 Refolding!
7.6 Symbol & domain language definition
7.7 Alternative Shared screen for groups
8 *** GURU: ADVANCED E2h FEATURES
8.1 * Optional URL parameters (for single page rendering)
8.2 * Per-Instance configuration
8.3 * LAN-only autoconfiguration
8.4 * Matomo open source analytics support
8.5 * Linkroute: A way to refer to other Pods
8.6 * Mirrorable: Offline regular backups


INTRODUCTION

A highly effective ideation, organization & publication model, using Etherpad and 🔗E2H software.

This document gives a functional introduction, at all levels — basic, intermediate & advanced.


An example:

    The CHT/Totalism knowledge commons.
        The public website has been assembled by hundreds of participants accross 10 years, and maintained by a full-time editor. The "internals" are an extended document set (staged to release, limited access, etc), accessible only to a core-group of operators.
 a view of the extent & inter-linkage of the documentation here.



*** BASICS: VOCABULARY & PRINCIPLES
FOR SOLO OR COLLABORATION


* Documents (or "pads") are contained in a pod.

A pod can have thousands of documents, that can be edited by many people at the same time.
The name also includes the infrastructure that powers it.


* All pads are accessible as online links

You can open any pad, as long as you have the link for it


* You can open documents either in VIEW or EDIT mode.

The difference is the first part of the link, before the document name.
You can find the EDIT button on each VIEW page!
### [!] make reverse true as well ...... @@e2h-todo
### [!*] consider hiding "Edit CSS" by default (as nobody does it EVER) ........ @@e2h-todo

Tip: For reverse and practicality, we reccomend trying to set up the 🔗workflow-bookmarklets.


* VIEW mode is ... normal websites

Rich-text ("hypermedia") documents — with structured text, images, graphs, charts, and videos; you can follow links both inside ("internal links"), and outside the pod.


* EDIT mode is ... real-time collaborative writing

Any number of people can edit the document simultanously, at the same time.
Every change is automatically saved, there is no special save button.
All changes persist, and can be easily rolled back. (So, nobody can break or vandalize things).
It's reccomended that when editing, you open the documents side-by-side, and refresh the 


* Editing is trivially simple

* You open the edit link.
* You scroll up and down the document.
* You position the cursor where you want to add something.
* You start writing.


—————


* Learning basics of computer use will help you use the system more effectively.

You might not consider yourself a "computer person".
But this is not about computers, but about collaborating with other people.
###AWK (You don't need to be a car person, but you still need to understand the simple basics of driving to stay on the road ... Except if you have a chauffer.)


* Your contribution to the pod is essential !

When collective adopted the pod system as the way to organize together, ideas expressed in other means (in chats, emails, unwritten conversations, etc) — will not reach others in the same way.

You might currently be more used to another system of interacting, but you should soon see the clear benefits of structured collaboration.
they do if you would express them in the pad system.
... Except if the chauffeur will write them for you.


—————


* Work with the pod keepers

Every collective appoints Mentors & Editors, which will make sure you are successful in contributing to the collective.
With their help, you will progressively master good contribution practices!


* Keep improving

By learning the more advanced concepts, you can significantly increase your collective's expressive power, and also help others.


* Learn & remember basic keyboard shortcuts

Basic keyboard use is essential to good 
See → 🔗workflow-basics !
    Learn to work rapidly.
    ctrl+pg up/down
    etc
    ------------------------
    [!] >david : make a test app ;-) ........ #dev.ideas





*** BASICS: USE


* Don't even try to work on documents on mobile

It works, but is a waste of time.
You will be much more effective & comfortable on a laptop.


* Search for content within the document

Use Ctrl+F in your browser to find things.
This will be especially useful with the syntax tags below!


* Learn and use other basic keyboard shortcuts

    * Pg Up / Pg Down
    * Ctrl+X , Ctrl+V
    More → 🔗workflow-basics !


* Don't delete content on your own

    Only strike it out!
    Wait for co-editors to acknowledge, and (re)move the content.


* Following positions & moving within pads
(You don't need to say if it's in document/pad, as it's apparant.)


    → "Ctrl+F"
Learn to use in-built search functionality of your browser.

    → "Read Planning!"
Open 🔗planning (in read mode!)

    → "Line 64"
You'll be asked to navigate to the edit mode of the pad,
or you will want to bring a position to the attention of other people.

There's lines on the left of the editor.
    * "let's go to one forty four":
        line 144 in pad:
        and, INDICATE YOU ARE THERE ("use checks" - make an x)
__________________________
    * "2.1 in TOC!":
        go to the "2.1" in Table of Contents


    → "Let's work on protocol-going"
Open that pad in EDIT MODE.


    → "Check!"
 ("Acknowledge!")
== "[xxxx]"

A space for participants to they "acknowledged!" or "checked!" a point.

The initiator opens it at some spot like this:
    "[x]"

Other participants find it & and add their mark:
    "[xxxx]"

The spot has been provably "acknowledged" or "signed" !
(in the pad, you will see different colored 'x' due to authorship colors)



* Styling & headering 101

Unlike Mediawiki, Markdown and other similar systems, Etherpad does this without syntax!


    * Just use Etherpad's text styles!

To style the text, just use the Etherpad styles:
    Bold (Ctrl+B) , Italic (Ctrl+I), Underline (Ctrl+U).
    (and combinations thereof)


    * Make Headers with Bold+Underline.


    * ... Indent 4 spaces for Subheaders.







*** INTERMEDIATE: E2h SYNTAX

Inspect all syntax in Edit mode: [...]


        * Internal links (Intralinks)
        example: "🔗ethering" (for this pad)

        * Auto-generated Table of Contents
        like "[TOC]"
        bold+underline text to create a heading
        drop increments of 4 spaces for subheadings
        helps a lot with content organisation!

        * Images by URL, via upload, or from other Pods
        like "[img:https://example.com/test.png|width]"
        width: "50%" or "300px".

        * Links-on-text
        Like "LINK WITH TEXT LABEL"

        * Cross-instance links (Cross-links)
        like "[:pod:padname]"
        example: "Wikipedia🔗Ted_Nelson"
    
        * Adopt Styles from other pads ("-css")
        a) "[style]" declaration:
            [style:padname].
            (includes "padname-css" pad as a stylesheet)

        b) with url parameter "CSSPAD":
            Example: http://localhost/CHT/E2H/e2h.php?_=cht5-frags&CSSPAD=hyperphoto

        * Image galleries (from Pods, or local storage)
        like "[###:part_of_filename]"
        (Example on ### page.)

        * Text-to-Graph (flowcharts, diagrams, networks, etc)
        using the "[graph]" directive & an own intermediate language
        details🔗glia-graph
        example🔗graph-index

        * Include maps
        Allows referring to Google MyMaps, a collaborative editor for public maps.
        * use as: "[gmap:google_mid|label]"
        * gives rendered link with .kmz and .gpx exports
        * (with Mirrorable) makes automatic offline backups
        * see on 🔗maps (the top list)!

        * Include content via Date
        as "[date:YYYY-MM-DD]" and then "[date++]"
        This auto-includes related content (images, ...) from the archives, as subheadings.
        Also useful as activity logs.

        * Explanations on text (like this)
        [extra:visible part|hovered part]:
    
        * Transclusion
###[!!**] lol move this out/document/something
1960's style !
        a) [TRANSCLUDE:url]
            * transclude any foreign page, via url

        b) [TRANSCLUDEX::padname:query_part]:
            * partial transclusion (by section, via "query_part")
            * TODO: full inner page <???>
            * TODO: page on any pod

        * File uploading
        Upload files to your pod via a HTML uploader.




*** INTERMEDIATE: SYMBOLS & CONVENTIONS)


Access Levels
###"lupine"

* Within a single pod, you will usually operate with documents

3 = public
2 = internal / members
1 = leadership


* Often, a document will have a main level (for example 3), with an aux document at another level (for example, 2):
    Two second will point to the first.
    ### [!!] E2H— solve this programmatically 



Collaboration & prioretization


        "BANGS", "HASHES": Marking tasks & improvement parts
[!!!] document the new, header-level syntax

        "!!!" == "bangs": fix this (content), or, do this (task)
            → prioritized tasks to work on

        "$$$" == "currently working on this"
            → one or few

        "###" == return to this
            → many, not top priority


        NAME TAGGING: Involving others

        tag people, for example on todos, with 
        (you can then find and cycle theirs/yours via Ctrl+F search)

        --------------- FOR
        ">leo" == "for leo":
            todo for leo!
        ">all !!!!!!" == "for all":
            something very important for all to look at.

        --------------- FROM/BY/VIA
        "<john" == "john>" == "from john":
            john wrote this part

        --------------- WITH
        "+jessica" == "with jessica"
            another person is involved / mentioned in what is written

        --------------- (DEACTIVATED REFERENCE)
        "_jessica"
            ... the mention was deactivated for some reason (for example: task deferred, etc)


        SIGNED COMMENTS & INLINE CONVERSATIONS

    (possibly, in early stage collaboration) 
        "<john>", or a shortened version, "<j>"
        
    when replying, you should use:
        <<<jane

    you can also add a date, like
        <<<junior , 2022-02-12



Adding content in the right place


        "GENERAL NOW-POINT" (for new, unsorted content)

    == "((NOW))"
(with double brackets)

Usually at the end of the document.


        "NOW-POINTS" (current working location)
    == "(NOW)"
    == "$$$$"

    CURRENT DOCUMENT WORKING LOCATIONS
        Find them (Ctrl+F)


        "NEW-POINTS" or "FORKS" (space for new unsorted content)
    == "<------------ (new)"

        Every living document should have at least one.
        A drop-off point for new fragments, usually written above.
        Sometimes as "NAMED FORKS" (for specific types of new entries)

    == "<------------ (new) More forks examples ↑"


        Cycle them with Ctrl+F.


        "EXPAND HERE"

    == "[...]"

        Contribute here!
        Links directly to pad.
        Used most commonly for imperfect lists & sections to improve.
        ### difference from now-points ?



Document structure & connections


        Header levels

Levels:
    * 0 = "***" (optional, if present)
    * 1 = no indent
    * 2 = first level of indent
    * and so on ...


        TOC: Table of contents

Auto-generated.


        Making links (to other documents)
### MERGE to manual

GOOD:
    1) https://normal.link (WITH PROTOCOL)
    2) LINK ON TEXT
    3) 🔗example
    4) TLM🔗another-pod

BAD:
    * somelink.whatever.com - ADD THE PROTOCL ( http:// )
    * www.blabla.com - THIS WORKS BUT ADD THE PROTOCOL ANYWAY



Corrections from Editors
###"Pod keeper"?


Accept editorial marks.
aka ANNOYANCE MARK
    == "¤¤¤"

You made a mess with style, indentation, syntax, etc:
    Try to figure it out.
    Look at how this is done elsewhere, you should be able to see it.
______________
    1) correct mistake
    2) note mistake down (to your log)
        write it down here, on XXX🔗editorial
    3) acknowledge:
        "corrected & noted down in X"

__________________________
There will be a "CORRECTIONS" section in non-published collaborative documents.
Corrections will be addressed to you from any editors.
Cross-out a correction to acknowledge.

// TMI //:
    Too Much Information.
    "Unmarked grave" category info.

//MISPLACED//:
    This needs to be a fragment in a different place.
    Otherwise it will get burried.
    The least, move it to TITLED FRAGMENTS.





*** ADVANCED: MAINTAINER CONCEPTS


Consider document purpose

What is the justification for writing (and for somebody else, reading) this?

Is this page not already covered by other, already existing sites?
    (But: Maybe you just want a co-curated index of other materials)

[...] ###


Write Quality Documentation !!
### //STUB//

From BAD to GOOD...

    5) "unmarked grave":
        a fragmented, long-winded ("detailed") log of a one-time event in an unmarked pad

    4) "sensible notes":
        foundation for a later-time analysis of "what went wrong / right"
        (sensible next pass: bold the good lines)

    3) "first distill":
        short instructions, how to do it well (as a checklist, as "tips" and "caveats")

    2) "draft protocol":
        rewritten and improved existing instructions

    1) "fully-fledged protocol":
        regularly-used, perfectly positioned (indexed + a first-time user could find it), several repetitions, intuitive, wide-use


Keep publishing

* Make sure you don't have public-intended documents "just sit there"!:
    Even if they're not finished - publish them on an index!

* Don't leak links to internal documents

* Make sure they're at least kind of ok:
    (or finish them to that state.)

* Mark them directly under title:
    See "MARK DOCUMENT STATE" above.


Styling basics

aka "AWESOME CSS GUIDE"
See → 🔗styling
#e2h #TODO : must come with every pod


Marking document state

Like this:
    < STATE >

:
    * STUB: placeholder or just a sketch
    * PRE-DRAFT: pre-revised, document structure not fixed
    * DRAFT: ready for final revisions
### consider with XXX🔗padwork marks system ...


Fragment tagging!

###


Assisting Editors

###


Organize & lead Etherbeamer sessions

🔗ethering-beamer


Simple & powerful theming

1) Default style if not specified:
    https://pad.totalism.org/p/CSS-default
    (or equivalent in your install)

2) Every site takes the "sitename-css" pad as CSS:
    example: this page, 🔗E2H, takes 🔗E2H-css
    (There is also a link to "Edit CSS" on each site, if not hidden.)

3) Via style imports inside the pad:
    "[style:padname]" will adopt a stylesheet, defined in the "padname-css" pad.

4) Via URL in optional parameter:
    "&customcss=http://e2h.middlemachine.com/E2H/css.css"
    Use the above .css file as the base for your theme.
    If you want to just mess with the colors a bit, it's best to find+replace current colors (which are used several times inside the .css).

5) Set custom theme via pad:
    "&CSSPAD=padname"


Hypothes.is annotation support

See → 🔗hypothesis !

either:
    A) via URL addition:
        add "&hypo" OR "&hypo&stick" (to include annotation mode in following links)
    B) by adding to any pad (to enable annotating there default):
        "[HYPOTHESIS]".




*** EXPERT: EDITORIAL & COLLABORATIVE CONCEPTS


Editorial & Domain specific syntax

Consult:
    → XXX🔗padwork
    → XXX🔗symbols


Leading reviews
### stub[!!]
[In-person group writing & coordination meetings]

Editors will lead "overviews", where:
(as originally practised at CHT, since CHT4A)

    * Everyone has an active laptop (so they can participate in writing)

    * No external service dependencies:
        Local Etherpad server
        Local network

    * Often recorded:
        (+ later timesynced to text)

    * Standard agenda:
        * first "overview" (pass through, comment on previous materials)
        * then "review" (brainstorm new stuff)
        ### link to more agenda docs

    * Regularity (about ~3 days)

#TODO: document, based on CHT🔗reviews !
See CHT🔗cht-metaprotocol, [...]



Leading overviews

###



Cleaning up Very Dirty Pads
(Protocol)

Pads will often get super messy.
Here's a placholder on how to resolve that.
### merge in other notes on this !!!!!!

:
    * "Level zero" headers:
        do a TOC overview
        place some super (or "level zero") headers ("***")

    * place proper "new-points"

    * resolve major open todos!:
        find "!!!!!!" and "??????"
        find now-points

    * overview & merge previous unfinished agenda

    * stage fragments:
        * adopt a symbol system for frags in pad
        * [...]

    * [...]



Refolding!

###
(usually includes fragment tagging)


Symbol & domain language definition

###


Alternative Shared screen for groups

VNC can also be used to provide a shared screen (especially nice with tablets/mobiles!), instead of a projector
Also see → 🔗ethering-beamer !




*** GURU: ADVANCED E2h FEATURES

(Some of these are documented in more details internally).


* Optional URL parameters (for single page rendering)
$$$$$$

Basic:
    * &STYLE to include CSS styling
    * &BTN to include 'Edit pad' button at the bottom
    * &BTNCSS to include "Edit CSS" buton
    * &css=[XXX] specify one of the built-in themes (found in E2H folder as css-XXX.css)
    * &customcss=[path to .css file] specify own .css theme. See Theming above.

Extra:
    * &noAnchors to disable autoinserting anchors on underline+bold text
    * &noTOC to disable TOC, even if inserted into page
    * &DEBUG to enable DEBUG mode
    * &CSSPAD=[padname] to, like with [style:...] directive, apply 'xxxxxx-css' to any doc

___  ___  ___  ___  ___  ___  ___  

Future:
    * specify content license
    * "Edit pad" button position: top/bottom/side
    * enable navigation in header (by specifying link to pad with a list of items)


* Per-Instance configuration

        Manage instance details (/__LOCAL_CONFIG)
        Manage Pods (/__LOCAL_RELINKING)


* LAN-only autoconfiguration
        (Host a Localnet instance with no Internet connection).
        Useful for deployments on laptops as Etherpad+E2h servers, retaining functioning links, ...


* Matomo open source analytics support
        see https://matomo.org (ex "Piwik")


* Linkroute: A way to refer to other Pods
        Discovers and routes to content on local machine, physically accessible resources (external drives), and from other trusted nodes (in a distributed / P2P DNS way)


* Mirrorable: Offline regular backups
        Uses E2T + cronjobs + DISTRO + git + git gui.
        Stores: .txt and .html versions.