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:

Etherpad   PHP  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




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




Features



:
    * 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, ust 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 below.

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.