Re: [ctlug] M$ Joy

[Steve Litt]

David Wolfe said on Wed, 7 Apr 2021 11:11:48 -0500

>[ Lindsay Haisley writes: ]
>> I don’t have time to deal with word processor that’s not WYSIWYG.
>
>Understandable from a get-work-done perspective. As you've pointed
>out, that's where most people live. Consider a traditional word
>processor UI like that in LibreOffice that uses one or more simple
>markup formats as its document representation.

LibreOffice native format is a zipped group of six (IIRC) interrelated
XML files. It's not something like Asciidoc that's human readable and
easy to modify outside of a UI.

> I think Lyx is an old
>project that does this with TeX, but I don't have much experience with
>those. I remember not being impressed, but what if it could be made
>better?

LyX is a spectacular program **if** you're committed to it and if your
expected output is PDF and nothing else. It's a horrible way to write
things expected to be HTML or ePub. Also, LyX requires substantial LyX
expertise if you do any "off road driving". I've been writing books,
for sale to the public, in LyX, for the last 20 years, and it's worked
well for me.

>> IMHO, Libre office has improved over the years I’ve used it
>> substantially more than most other project programs.
>
>IMHO, LibreOffice has worked very hard matching MS Office

As I posted in another email, I'm not a fan of LibreOffice. But I have
some other ideas...

First of all, if you're writing a book with very few styling
requirements, AsciiDoc just might be something that would satisfy
Lindsey. It's not WYSIWYG, but it's sub-one-second compilable to PDF,
so at any point you can see what's happening on the
layout/font/appearance front. Sort of like the "see in graphical
mode" feature of WordPerfect 5.1. Not requiring a mouse, Asciidoc's
*much* faster authoring than any word processor or something like LyX.
And if you need more formatting and features, you can upgrade to its
big brother, Asciidoctor.

I'm thinking that if the majority of your document is simple, but some
things, like your title page and copyright page, are complex with
exacting formatting needs, you can do each of those pages in Inkscape
(SVG), and link those into the document at the proper places. SVG
incorporates seamlessly into HTML, and if it doesn't work directly into
PDF, it can be auto-converted to encapsulated PDF or whatever before
the entire document is converted. This is what LyX does with graphics.

I'm also looking into something called Restructured Text and a program
called Sphinx that seems to be a front end for Restructured Text. It's
complicated and I don't think would be appropriate for Lindsey.

Another great text-only format you can do in any editor is Plain TeX
(***NOT*** LaTeX, which requires a Ph.D to do right). It has the
most of the advantages of Asciidoc but is much more versatile, although
it authors a little slower because you have to actually spell out style
names. Plain TeX is meant to compile to PDF, but a suitable subset of
Plain TeX could be used to simultaneously author valid-XML HTML5, and
therefore ePub. My biggest problem with Plain TeX is that using
anything other than TeX fonts is difficult, but I'm still looking into
it.

For about 8 years I've been trying to create a text-editor created
format called Stylz, which would do all this stuff the right way.
Unfortunately, it's a difficult programming project, and other than a
couple test documents, I haven't gotten it working. However, last night
at an online GoLUG meeting, I met a guy who created a similar product
for his own books, and I'll be looking into that.

Emacs Org-Mode is another possibility if you drive on that side of the
road, but I'm pretty sure that wouldn't be something Lindsey would be
interested --- it's a lot of work.

There's also an outliner called Leo, which you can author entirely as
an outline with headlines that do or don't contain body text, and then
(I think) you can run a converter program, possibly one you'd need to
create yourself, to turn it into a ready made book, probably either PDF
or HTML/ePub. This isn't appropriate for Lindsey, because it's a huge
system with huge capabilities requiring a lot of knowledge: It's a
commitment. I'm copying the Leo list on this email.

I feel everybody's pain. As far as I know, there's not a single piece
of software out there that authors quickly and yet does consistent,
styles-based formatting and outputs to both PDF and HTML. But I'll keep
searching.

SteveT

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

[Edward K. Ream]

On Thu, Apr 8, 2021 at 7:55 AM Steve Litt <sl...@troubleshooters.com> wrote:

Hi Steve. Thanks for the summary.  I'm not sure I have the attributions correct below, but here are my comments.

> I'm also looking into something called Restructured Text and a program called Sphinx that seems to be a front end for Restructured Text. It's complicated and I don't think would be appropriate for Lindsey.

Imo, Sphinx + rST are relatively easy to learn. Those tools should suffice to write almost any book.

> There's also an outliner called Leo, which you can author entirely as an outline with headlines that do or don't contain body text, and then (I think) you can run a converter program, possibly one you'd need to create yourself, to turn it into a ready made book, probably either PDF or HTML/ePub.

Hmm. It would be nice if commentators tried out the tools they are describing.

Leo's rst3 command is the "converter" program. rst3 complements rST/sphinx as follows:

- Can generate multiple documents from a single outline: one per @rst node en.

- Automagically creates rST section markup using outline structure.

  This means you can reorganize your paper or book freely, a huge advantage.

- Optionally generates intermediate files for sphinx.

> As we have been describing on leo-editor, rst3 supports a very few frills, including ignoring parts of the @rst tree entirely, or not generating section markup for one or more nodes, thereby allowing authors to organize long sections using suboutline.

> This isn't appropriate for Lindsey, because it's a huge system with huge capabilities requiring a lot of knowledge: It's a commitment. I'm copying the Leo list on this email.

Did the commentator mean that Leo itself is a huge system? True enough, but working through Leo's tutorials is all someone needs to do to start writing their opus.

> I feel everybody's pain. As far as I know, there's not a single piece of software out there that authors quickly and yet does consistent, styles-based formatting and outputs to both PDF and HTML. But I'll keep searching.

To summarize my responses to such discussions:

1. You're screwed if you insist on wysiwyg. How do you create a table of contents?

2. Some people spend their whole life complaining about missing tools, without any clear idea of what they want. Others use the tools that do exist.  Some people even help improve the tools they use :-)

Edward

[Edward K. Ream]

On Friday, April 9, 2021 at 12:41:41 PM UTC-5 Edward K. Ream wrote:

>> I feel everybody's pain. As far as I know, there's not a single piece of software out there that authors quickly and yet does consistent, styles-based formatting and outputs to both PDF and HTML. But I'll keep searching.

> 1. You're screwed if you insist on wysiwyg.

...

> 2. Some people spend their whole life complaining about missing tools, without any clear idea of what they want.

I apologize for the insulting tone. A more helpful response would be something like this:

1. Those who are planning major writing projects would be well advised to make a serious study of the strengths and weakness of the major contenders, including Jupyter, LaTeX, reStructuredText, and Leo. And yes, it will take some study. wysiwyg editors and simplistic markup languages like markdown are too limiting. Better to invest in more powerful tools.

2. It is a great mistake to underestimate the capabilities of existing tools.

I have made this mistake several times. 30 years ago, I despaired of using Emacs because I didn't understand that tab completion makes it unnecessary to remember full command names, or to type them. Had I understood this, I would likely have based Leo on Emacs. Leo's entire history would have changed, and I would not have spent much of the last 30 years dealing with tangential editor-related issues.

In short, please take the time to study what is already possible. Major tools typically have dozens or even hundreds of contributors. It would be impossible to do better on one's own.

HTH.

Edward

[David Szent-Györgyi]

On Sunday, April 11, 2021 at 4:14:30 AM UTC-4 Edward K. Ream wrote:

1. Those who are planning major writing projects would be well advised to make a serious study of the strengths and weakness of the major contenders, including Jupyter, LaTeX, reStructuredText, and Leo. And yes, it will take some study. wysiwyg editors and simplistic markup languages like markdown are too limiting. Better to invest in more powerful tools.

2. It is a great mistake to underestimate the capabilities of existing tools.

I have made this mistake several times. 30 years ago, I despaired of using Emacs because I didn't understand that tab completion makes it unnecessary to remember full command names, or to type them. Had I understood this, I would likely have based Leo on Emacs. Leo's entire history would have changed, and I would not have spent much of the last 30 years dealing with tangential editor-related issues.

In short, please take the time to study what is already possible. Major tools typically have dozens or even hundreds of contributors. It would be impossible to do better on one's own.

Edward is absolutely right in recommending using existing tools when possible. 

I am looking for a markup language for plain-text files, some of which are documentation meant for PDF or ODF, some of which are plain text meant for conversion via templates to static HTML5 for a Web site. Has anyone else worked with AsciiDoc format?

AsciiDoc is meant to be less ad-hoc than Markdown and the variants thereof. It is meant to be semantically equivalent to DocBook XML, and its creators are early in an effort to write a specification  complete with an open Technology Compatibility Kit.

The creators of AsciiDoc offer Asciidoctor, a "fast, open source text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook, PDF, and other formats"; AsciiDoctor is cross-platform, written in Ruby; AsciidoctorJ runs on a Java Virtual Machine, and Asciidoctor.js in JavaScript environments, including Web browsers. The leaders of the Asciidoctor project write that AsciidoctorJ and Asciidoctor.js need to develop independently of Asciidoctor, which is one motivation for the creation of a specification and TCK. 

The Python implementation, AsciiDoc-py, is limited to legacy syntax for AsciiDoc. 

 

[tbp1...@gmail.com]

The VR3 plugin for Leo can render Asciidoc to HTML using an Ascidoc command line processor, and then display it inside Leo in its display pane.  I have found that the conversion is slow for larger asciidoc trees, though (not because of Leo but because of the processor).  The flavor of HTML would depend on the external processor.

You write your document as a subtree in Leo.  You can render any node or subtree, or the entire subtree.  Node headlines become section titles in the rendered result.

[Steve Litt]

Edward K. Ream said on Fri, 9 Apr 2021 12:41:30 -0500

>On Thu, Apr 8, 2021 at 7:55 AM Steve Litt <sl...@troubleshooters.com>
>wrote:
>
>Hi Steve. Thanks for the summary. I'm not sure I have the attributions
>correct below, but here are my comments.
>
>> I'm also looking into something called Restructured Text and a
>> program
>called Sphinx that seems to be a front end for Restructured Text. It's
>complicated and I don't think would be appropriate for Lindsey.
>
>Imo, Sphinx + rST are relatively easy to learn. Those tools should
>suffice to write almost any book.

Thanks for the tip! I'll put some more time into Sphinx + rST.

>
>> There's also an outliner called Leo, which you can author entirely
>> as an
>outline with headlines that do or don't contain body text, and then (I
>think) you can run a converter program, possibly one you'd need to
>create yourself, to turn it into a ready made book, probably either
>PDF or HTML/ePub.
>
>Hmm. It would be nice if commentators tried out the tools they are
>describing.

:-) I've tried Leo many times, but still don't know even 3% of it.

>
>Leo's rst3 command is the "converter" program. rst3 complements
>rST/sphinx as follows:
>
>- Can generate multiple documents from a single outline: one per @rst
>node en.
>- Automagically creates rST section markup using outline structure.
> This means you can reorganize your paper or book freely, a huge
> advantage.
>- Optionally generates intermediate files for sphinx.
>
>> As we have been describing on leo-editor, rst3 supports a very few
>frills, including ignoring parts of the @rst tree entirely, or not
>generating section markup for one or more nodes, thereby allowing
>authors to organize long sections using suboutline.
>
>> This isn't appropriate for Lindsey, because it's a huge system with
>> huge
>capabilities requiring a lot of knowledge: It's a commitment. I'm
>copying the Leo list on this email.

>Did the commentator mean that Leo itself is a huge system? True
>enough, but working through Leo's tutorials

><http://leoeditor.com/tutorial.html> is all someone needs to do to
>start writing their opus.

I was the commentator. I've worked partially through the tutorials
several times, but got bogged down and went on to other things. I'm
speaking as a Leo outsider or newbie here: Leo has so many capabilities
that learning the majority of it is a serious commitment. All the
capabilities are real, needed things, I have no doubt of that. All I'm
saying is learning something that capable is a commitment, and in my
experience a linear walk through several tutorials wasn't enough to get
me capable beyond regular outline workflow.

I'll try again when I get some time.

>> I feel everybody's pain. As far as I know, there's not a single
>> piece of
>software out there that authors quickly and yet does consistent,
>styles-based formatting and outputs to both PDF and HTML. But I'll keep
>searching.
>
>To summarize my responses to such discussions:
>
>1. You're screwed if you insist on wysiwyg. How do you create a table
>of contents?

That's my opinion also, but Lindsey's workflow, priorities and past
experience lead him to WYSIWYG.

>
>2. Some people spend their whole life complaining about missing tools,
>without any clear idea of what they want. Others use the tools that do
>exist. Some people even help improve the tools they use :-)

Yes, I didn't give full context. Earlier in the thread, I had remarked
that because of LibreOffice's handling of styles, it was unsuitable for
long documents, and gave (as I remember) Bluefish, Leo, MS-Word,
Inkscape, LyX, Stylz (which is not complete), org-mode, and several
other alternatives. Lindsey basically said LibreOffice was good enough
for him, and for times sake he likes WYSIWYG. In one situation I agree
with him: If I had a quick 1 pager to write, I'd use either LibreOffice
or Inkscape and be done with it, not a more robust tool meant to
produce bigger and higher quality output.

So it wasn't Lindsey complaining about missing tools, it was me. And
I'm referring to exactly one thing: The ability to create a style on my
own, with a name created by me, and have that style stay a style all
the way through the compile chain until being translated to an
appearance in the very last process. A good example is CSS:

p.story{font-style: italic; margin-right: 1em; margin-left: 1em;}

and later

<p class="story>It was a dark and stormy night,
and seated round the campfire was a bunch of dark
and dusty brigands. When the captain said to Antonio,
"Antonio, tell us a story", Antonio stood and related
the following:

It was a dark and stormy night ...
</p>

The cool thing about CSS in HTML is that, if the HTML is actually meant
to produce an ePub, the p.story style stays a style all the way
through, and is translated to appearance by the ePub reader.

In LaTeX, my Story "environment" (TeXish for paragraph style) is as
follows:

\newenvironment{storyL}{
\par
\begingroup
\leftskip 0.4in\rightskip 0.4in
\it
\noindent{.\dotfill{}.\par}
%~\vskip -0.3in
}{
%~\vskip -0.05in
\par\noindent{.\dotfill{}.\par}
\endgroup
%~\vskip 0.0in
~\\
}

Once again, I named the style, I defined it, and that style stays a
style until conversion to either a PDF or a dvi (which is a
non-editable file convertable to PDF).

The ability to name and define a style that stays a style throughout
the editable files of the entire compile chain is all I want out of
life, assuming no premature conversion of the style p.story to
appearances, and assuming that in each format (html, ePub and PDF) I
can create a different style to appearance mapping for p.story, that
gets applied at the very last minute. Without Pandoc.

Markdown has no such ability. Neither does AsciiDoc. AsciiDoctor
*might*, but it appears to be very complicated. LyX' HTML exporter does
very premature conversions of styles to appearance, so that the
resulting HTML loses most of its styles, meaning you can't convert from
HTML to something further. What I've briefly read about Sphinx + rST is
that it might be able to --- perhaps with the use of rolls, but I've
found no example on the Internet, so I have to experiment.

In a perfect world I'd get Stylz perfected and running, because that
would be a technically-aware author's dream: Write once, fast, keyboard
only, and output to anything, including PDF, HTML and ePub, each with
a style to appearance mapping suited to reader needs according to
format capabilities and limitations of the format.

If I ever do get Stylz running, I'll do whatever it takes to make it
Leo compatible so somebody can author in Leo, with body text being
Stylz.

[tbp1...@gmail.com]

With Sphinx/Rst you can change the css stylesheet and get it to use yours instead.  For example, the difference between the appearance of the docs on the Sphinx site and those on ReadTheDocs is the CSS stylesheet.  I'm not sure how you can get Sphinx to use a newly named style - one that it doesn't inherently know about - for a given paragraph or section, but I wouldn't be surprised if there's a way.

[Edward K. Ream]

On Mon, Apr 12, 2021 at 12:24 PM Steve Litt <sl...@troubleshooters.com> wrote:

I've worked partially through the tutorials several times, but got bogged down and went on to other things.

For you, I would suggest working through Leo's rst3 tutorial. You don't need to know about clones, or scripting, or much else except the basic terminology that an "x node" is a node whose headline starts with "@x".

Feel free to ask questions here.

So it wasn't Lindsey complaining about missing tools, it was me. And
I'm referring to exactly one thing: The ability to create a style on my
own, with a name created by me, and have that style stay a style all
the way through the compile chain until being translated to an
appearance in the very last process. A good example is CSS:

p.story{font-style: italic; margin-right: 1em; margin-left: 1em;}

and later

<p class="story>It was a dark and stormy night,
and seated round the campfire was a bunch of dark
and dusty brigands. When the captain said to Antonio,
"Antonio, tell us a story", Antonio stood and related
the following:

It was a dark and stormy night ...
</p>

Thanks for the clarifications. I never gave this aspect of html any thought. reStructuredText has the "raw" directive, so should be possible to do this with rST.

Edward