lwdx

This repo is a placeholder for a still-unnamed app currently under development.

Lightweight document transformations & assemblies, based on familiar markups and simple tools.

• Accept and process content authored in three interoperable input formats: XDITA xml, HDITA html5, MDITA markdown (Note: this interop is a fundamental premise of LwDITA)
• Assemble documents from maps that transclude modular, structured topics (this feature is straight from DITA)
• Based on the emerging OASIS LwD standard (altho full compliance is not guaranteed)
• The goal is roundtrip conversions among all three formats for freedom+flexibility in authoring+publishing (note tho that MDITA may be limited in faithfully representing XDITA and HDITA)
• We desire straightforward handling of XML mixed content, and therefore...
• We take a DIY approach (based on the Go stdlib XML encoder) over the horrors of Golang's XML annotations.

Contains

• CLI commands
• Golang API
• Web UI

Features

• simplex sigillum veri
• Rely on Golang's encoder/xml package for parsing & tokenization (altho it fumbles with XML namespaces)
• Hide as much XML & DITA complexity as possible (IAW the Bell Labs UNIX "NJ Style": It is slightly better to be simple than to be correct.)
• Format input files opinionatedly (like gofmt), which simplifies diff'ing for changes under version control
• Note that MDITA (markdown) parsing uses the goldmark library. Goldmark is based on CommonMark and so it might not on its own achieve full MDITA compliance.
• (temporarily shelved) For purposes of comparison and exploration, can write out parse trees generated by xmlx, etree, mxj, x2j, Go html

License

• AGPL
• Note tho that subsidiary libraries under github.com/fbaube are MIT license
• Discussion of AGPL
• (Future:TBS) Dual licensing to provide an option for unencumbered commercial use

Missing

• Automated tests
• XML DTD-style entity substitutions (did you get the memo? for large transclusions, use DITA conref)
• Details of comment handling in Markdown, and how it can support roundtripping for complex LwDITA tags (note that LwDITA relies on CommonMark with extensions)

TODOs & Roadmap

• As an exercise, write a command line conversion (dogfooding) tool, DITA => XDITA/HDITA, to apply to the source of the official LwDITA spec (and its drafts)
• (Optional) Implement Pandoc-style heading notations in MDITA, i.e. {#identifier .class .class key=value key=value}. For example, to specify that a file describes a Task: # Installation { .task }
• Implement character entities, partly to enhance the input parser comparisons
• Publishing: this is the first step to usefulness, and will be done along the lines of the DITA-OT's preprocessing stage, so as to generate "Normalized LwDITA", so that the DITA-OT can be used for output processing
• A schema-driven WYSIWYG IBE (in-browser editor)
• Enhanced support for common DITA mechanisms like conref files and glossary files
• Support for LwDITA-style specialization-by-example
• Not roadmapped yet: Support for ditaval files for conditional publishing

Contributing

• Contact me at fbaube at iki daaht fi

mermaid test

  graph LR;
      A-->B;
      B-->C;
      C-->D;
      D-->E;
      B-->B1
      C-->C1
      D-->D1

Loading

flowchart LR
    subgraph m[Mermaid.js]
    direction TB
        S[ ]-.-
        C[build<br>diagrams<br>with markdown] -->
        D[on-line<br>live editor]
    end
    A[Why are diagrams<br>useful?] --> m
    m --> N[3 x methods<br>for creating<br>diagrams]
    N --> T[Examples]
    T --> X[Styling<br>and<br>captions]
    X --> V[Tips]
    
 
    classDef box fill:#fff,stroke:#000,stroke-width:1px,color:#000;
    classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
    class A,C,D,N,X,m,T,V box
    class S spacewhite

Loading