E2H E2H: Etherpad Hypermedia


Collaboratively and simply author single documents, or Wiki-like websites.
Auto-generates HTML by transforming and styling Etherpads.

By @dcht00 (david@middlemachine.com / CHT hackbase), with:

https://translatewiki.net/images/thumb/6/6f/Etherpad_lite.svg/200px-Etherpad_lite.svg.png Etherpad   https://php.net/images/logos/php-med-trans.png PHP  https://seeklogo.com/images/C/css-logo-36E0A08420-seeklogo.com.gif CSS, Graphviz, ...


Last updated:
    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

Table of Contents
1 Some examples
2 Features
3 Works with...
3.1     Existing Etherpad instances
3.2     Your own Etherpad instance
4 USAGE
4.1     Basic Etherpad editing and styling
4.2     Additional Syntax, to insert:
4.2.1         * Images by URL, via upload, or from other Pods
4.2.2         * Links-on-text
4.2.3         * Auto-generated Table of Contents
4.2.4         * Internal links (Intralinks)
4.2.5         * Cross-instance links (Cross-links)
4.2.6         * Adopt Styles from other pads ("-css")
4.2.7         * Image galleries (from Pods, or local storage)
4.2.8         * Text-to-Graph (make flowcharts, diagrams, networks, etc)
4.2.9         * Include maps
4.2.10         * Include content via Date
4.2.11         * Explanations on text (like this)
4.2.12         * Make 1960's style transclusion
4.2.13         * File uploading
4.3     New Features(2017/2018)
4.3.1         * Per-Instance configuration
4.3.2         * Matomo open source analytics support
4.3.3         * Hypothes.is annotation support:
4.3.4         * Local network autoconfiguration (Host a Localnet instance with no Internet connection):
4.3.5         * Linkroute: A way to refer to other Pods
4.3.6         * Mirrorable: Offline regular backups
4.4     Theming
4.5     Page Rendering Optional Parameters
5 Deployment
5.1     #1: Use my proxy [Simplest!]
5.1.1         For Etherpad-Lite instances
5.1.2         For old Etherpad instances (Mozpad, TitanPad, ...)
5.2     #2: Self-hosted
6 Future development / Todos
7 Support the development
8 Notes



Some examples
:
    * The site you are looking at!
    * https://totalism.org/ : 🔗season4𝌡, 🔗manual𝌡, 🔗alike𝌡, ...
    * http://www.ooooo.be/etherhtml/e2h.php?_=S14
    * [...]




Features

E2H->HTML websites Author Etherpad documents->E2H Author Etherpad documents->Using the basic styles (Bold, Italic, Underline,...) Author Etherpad documents->Using the extended E2H syntax E2H E2H HTML websites HTML websites Author Etherpad documents Author Etherpad documents Using the basic styles (Bold, Italic, Underline,...) Using the basic styles (Bold, Italic, Underline,...) Using the extended E2H syntax Using the extended E2H syntax


:
    * insert images
    * simple internal links (Wiki-like), and cross-instance links
    * hyperlinks-on-text
    * auto-generated Table of Contents
    * page footer with "Edit pad" and "Edit CSS" buttons
    * themes (editable pad as CSS, or static CSS styling)
    * powerful text-to-graph capability, using Graphviz
    * transclusion (inclusion of pages by reference) and partial transclusion
    * support for Pods:
        * for simple addressing of content on other Etherpad/Mediawiki instances
        * seamless local mirroring of currently-inaccessible content !
    * SSL support
    * Matomo analytics support
    * [...]





Works with...

    Existing Etherpad instances

All modern Etherpad-lite instances, like:
    * https://pad.totalism.org/
    * http://piratepad.be/
    * http://piratenpad.de
    * http://board.net (example)
    * [...]

Old Etherpad instances:
    * Mozpad:
        https://festival.etherpad.mozilla.org/-kylTRteukS ->
        https://festival.etherpad.mozilla.org/ep/pad/export/-kylTRteukS/latest?format=html
    * Titanpad works:
        https://titanpad.com/3SOIzaVeOi ->
        https://titanpad.com/ep/pad/export/3SOIzaVeOi/latest?format=html
    * http://pads.ccc.de/
    * [...]
If you are having problems using it with any specific pad, or need to whitelist a server, contact me.


    Your own Etherpad instance

Contact david@middlemachine.com if you need any help setting this up for your small site, project or organisation.

If you want your own deployment, see 🔗E2H#Deployment𝌡.

You can use the current hosted deployment freely, after I whitelist your Etherpad instance (see below).





USAGE

    Basic Etherpad editing and styling

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

Combinations are also possible.
Some are interpreted to set document structure: Bold+Underline makes a title.


    Additional Syntax, to insert:

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

        * Links-on-text
        like "[ https://example.com|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 (make flowcharts, diagrams, networks, etc)
        using the "[graph]" directive, parsed via own intermediate language, to Graphviz
        (see 🔗graph-beer𝌡 for a simple 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]:
    
        * Make 1960's style transclusion
        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
        Simple HTML file uploads, referencable as a Pod.


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



    New Features(2017/2018)

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

:
        * Per-Instance configuration
        files: __LOCAL_CONFIG (manage instance details), __LOCAL_RELINKING (manage Pods)

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

        * Hypothes.is annotation support:
        * either via URL:
            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]".

        * Local network autoconfiguration (Host a Localnet instance with no Internet connection):
        Useful for deployments on laptops as etherpad+E2H servers, retaining functioning links, ...

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






    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 "padname-css" stylesheet.

4) Via ia 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 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

Unsure??:
    * &CSSPAD ... Don't think it works atm? Check...

___  ___  ___  ___  ___  ___  ___  

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)






Deployment

    #1: Use my proxy [Simplest!]

Use the "https://e2h.totalism.org/e2h.php" proxy with your pad server.
Please contact me in this case, so I can whitelist your service.


        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

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𝌡, or hire me to help you set this up.




Notes

The Etherpad logos by Marcel Klehr are licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.



(Site generated by E2H, an "Etherpad hypermedia" project by @dcht00). Creative Commons License
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.


Edit Site

Edit CSS