[ale] [OT] Document formatter?

[Steve Litt]

On Mon, 2 Apr 2018 08:11:32 -0400
leam hall via Ale <ale at ale.org> wrote:

> I'm trying to learn multi-purpose tools. Right now I need something to
> document my Ruby code and to also take text based fiction and turn it
> into a pdf with bold headers and appropriate page breaks. As a last
> resort I can open the text doc in LibreOffice and save as a PDF.
> 
> A friend uses Doxygen for his project, I'm looking for some options.
> The goal is to be able to run it on the command line.
> 
> Suggestions?

Funny you should mention this. Right as we speak, I'm implementing the
standard and conversion software for Stylz, a 100% styles based
authoring format that, when completely implemented, will be write once,
read everywhere. It's like Asciidoc, except it prioritizes quick
authoring and "we do it all for you" a little less than Asciidoc, but
it completely enables use of arbitrary styles. As long as you keep your
style names short, Stylz should author faster than LaTeX, LyX,
LibreOffice. It will be less magical and easier to actually use than
stuff like Pandoc, Docbook, XSLT and the like. Style definition is done
in CSS (html, ePub) or LaTeX (PDF) completely outside of the .stylz
file.

It's implemented as a bunch of tools used at the command prompt.
The .stylz file is converted to a sort of pidgeon XML via two or three
awk programs. These are written already. Once the information is in
XML format, I can have my way with it using an XML parser (leaning
toward Python xml.etree.ElementTree). 

Next step are an XML to HTML converter, XML to ePub, and XML to LaTeX
(I'll probably need some help on that one). It would also be possible
to create a Stylz to PDF slide presentation converter. The advantage of
Stylz->Slideshow over Asciidoc/Slidy is that with Stylz, making your
own style to appearance relationships is *much* easier, meaning that
your slideshow looks like *you* want it to look, not the way the authors
of Asciidoc thought would be best.

None of these converters are written yet, although I'm in the
explorational phase of the XML to HTML converter.

Two other handy tools have been written: One to test a file for being
well formed XML, and the other to go through a Stylz file and report
all paragraph and character styles named. This is important when
writing your CSS and LaTeX style definitions, and also, if enabled with
copy and paste, an easy way to get an entire style declaration into
your document while writing new content.

I have a 3 year old,  half accurate definition of Stylz here:

http://troubleshooters.com/projects/stylz/

The preceding document is much more featureful and complex than what
I'm doing now: What I'm doing now is a subset of that 3 year old
document. Also, I've decided against directory tree key-value
hierarchies: Those sound so appealing, but when you actually go to
create them, they're slow and error prone. I'll probably have the
document metadata and the build info in Yaml form,  or perhaps even the
ancient Windows conf file 2 dimensional things where categories are in
square brackets,  with key-value pairs bestriding an equal sign below
them.

Stylz is 100% CLI and will remain so, except possibly for style cut and
paste helpers. You create Stylz in the fastest editor you know: I use
Vim. It's built for mouse-free use, for touch-typists.

Stylz is meant to create long documents with very consistent styles
throughout. In my opinion it would be silly to make resumes or letters
in Stylz: LibreOffice is much better for those things.

Once I get the XML to HTML converter done, Stylz will achieve an MVP
(Minimal Viable Product) for geeky early adopters.

SteveT

Steve Litt 
April 2018 featured book: Troubleshooting Techniques
     of the Successful Technologist
http://www.troubleshooters.com/techniques