[ style:css-sidetoc]

            You write Etherpads
and they are transformed 2
                hypermedia documents

Comrades!
Author all sorts of web documents, or use as a content management system for wiki-like sites.
E2h auto-generates HTMLs by transforming and styling Etherpads.

Last updated @ 2020-05-01
by @dcht00 (david@middlemachine.com / CHT hackbase).

    2014-10-xx first version, hacked @ TechInc, Amsterdam
    2015-10-30 readying for release
    2016-01-29 added CSS support
    2016-10-07 feature additions
    2017-04-19 more feature additions
    2018-03-21 moved to new pad server
    2018-07-30
    2019-03-26
    2020-05-01





    * insert images:
   

    * simple internal links (Wiki-like), and cross-instance links:
        🔗E2H#Deployment

    * hyperlinks-on-text, like this, or image

    * auto-generated Table of Contents:
        * either on side, auto-hide or on top of document (depending on which theme you invoke)
        * responsive (Portrait / Landscape modes)

    * collaborative theming:
        (via pad-editable CSS files, for this page: 🔗E2H-css)

    * powerful text-to-graph capability (using a simplified Graphviz syntax)

    * transclusion (inclusion of pages, or their parts, by reference)

    * support for Pods:
        * simple addressing of content on other instances (E2h, Mediawiki, ...)
        * seamless mirroring of content (including offline!)
        * latent addressing of resources, accessible depending on user's personal pod resolution list

    * emoji support 😸🤠🦷🧜‍♀️🧶🧠

    * deploy to own web domains, with custom URL path logic
    (with Apache mod_rewrite)

    * SSL (with Let’s Encrypt)

    * optional analytics (with Matomo)

    * [...] !





Website Examples


* totalism.org pod:
    * ( this website )
    * the old index: https://totalism.org
    * systematics like 🔗alike, ...
    * graphs like 🔗graph-index, ...
    * also see 🔗puzzles, ...
    * hosting files: here

* ... transforming pads from other Etherpad pods (and with custom styling):
    * blue-narchy, via framapad.org
    * *globalista*radio*kit*, via pads.ccc.de


* ooooo.be own instance:
    * http://www.ooooo.be/etherhtml/e2h.php?_=S14
    * http://www.ooooo.be/etherhtml/e2h.php?_=daemonshellscripts
    * http://www.ooooo.be/etherhtml/e2h.php?_=techotsukumogami
    * http://www.ooooo.be/etherhtml/e2h.php?link=annuel2.framapad.org/p/blue-narchy


* internal CHT instance:
    ^CHT🔗CHT ( accessible only with the right routing keys )






USER MANUAL


    Style 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)

        (Bold+Underline together makes headers, 4 spaces indent.)



    Additional Syntax:

To insert... :
(Inspect syntax in Edit mode: [...])

        * 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 "TEXT LABEL"

        * 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!
    
        * Internal links (Intralinks)
        example: "🔗E2H" (for pad of same name)

        * 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 "[pics:part_of_filename]"
        (Example on 🔗trucko page.)
    
        * Text-to-Graph (flowcharts, diagrams, networks, etc)
        using the "[graph]" directive, parsed via own intermediate language, to Graphviz
        (see 🔗oversee for an example)

        * 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
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.


Arbitrary small syntax (might get more power in the future):
    (move this to #ethering !)
    * "    * ":
        a bullet (unordered list, or a "set")
    * "    > ":
        an option (either-or list, or a "set of options")
    * "[...]":
        add more bullets here!
    * "???" or "(?)":
        needs more clarification
    * "(new)":
        place in pad to add new content, to be sorted later
    * [...]


    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: 🔗E2H takes 🔗E2H-css
    (There is also a link to "Edit CSS" on the bottom of each site, by default.)

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"




    Page Rendering (optional URL parameters)

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)




    Advanced Features

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

        * 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")

        * Hypothes.is annotation support:
        * either via URL addition:
            add "&hypo" OR "&hypo&stick" (to continue browsing site in annotation mode)
        * ... or by adding to any pad (to make annotation there by default):
            "[HYPOTHESIS]".

        * 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.

    * [...] <----------------------- (new)





Deployment

For self-hosted E2H for your small site, project or organisation, contact david@middlemachine.com .

E2H works with all modern Etherpad instances.

There are two ways to use it.



    #1: Use my proxy [Simplest!]

### add pad.land !!!!!!!
Use the totalism.org E2h proxy with your pad server.
    A) use the current hosted deployment freely, after I whitelist your Etherpad instance

You can use the The E2h deployment on as long as they are whitelisted.

For example:
    * https://pad.totalism.org/
    * https://board.net
    * http://piratepad.be/
    * http://piratenpad.de
    * [...]

Contact me in this case, so I can whitelist your Etherpad service.

Also contact me if you are having problems using it with any specific pad, or need to whitelist a server.



        For Etherpad-Lite instances

Example:
    * https://e2h.totalism.org/e2h.php?link=pad.totalism.org/p/planning&STYLE&BTN&noTOC&CSSPAD

Link:
    https://e2h.totalism.org/e2h.php?link=PAD
    'link' = link to the Etherpad-lite pad url, only part after "http://"


        For old Etherpad instances (Mozpad, TitanPad, ...)

Example:
    * https://e2h.totalism.org/e2h.php?link=teams.piratenpad.de&pad=D7Krh5QPiy&NONLITE&STYLE
    * https://e2h.totalism.org/e2h.php?link=titanpad.com&pad=3SOIzaVeOi&STYLE&BTN&NONLITE&CSSPAD=E2H
    * https://e2h.totalism.org/e2h.php?link=festival.etherpad.mozilla.org&pad=-kylTRteukS&STYLE&BTN&NONLITE :
        (mozilla etherpad down 2017-09-14)

Link:
    https://e2h.totalism.org/e2h.php?link=DOMAIN&pad=NAME&NONLITE
    ------------------------
    link = domain only
    pad = pad name
    Add "&NONLITE" parameter.




    #2: Self-hosted

To use it with your own Etherpad instance, but with the totalism.org E2H, it will need to be whitelisted. Send me a mail.

Contact david@middlemachine.com if you're interested in the source code and setup instructions.
Some contribution to help support the development is expected.


Future development / Todos
See 🔗e2h-todo !
Directions:
    * hypertheory, see 🔗text and 🔗hyperreader
    * Ted Nelson's view of the web, see ^Wikipedia🔗Project_Xanadu
    * also see 🔗workflow, for developments to cover the CHT Hackbase's case
    * [...]


Support the development

🔗donate, comission to set up your own custom instance, or join the 🔗coop.

Contact david@middlemachine.com .


Acknowledgements
Etherpad, CSS, PHP, Graphviz
The Etherpad logos by Marcel Klehr are licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.