Re: Tools for writers
Hi, On Sun, Nov 03, 2019 at 02:29:02AM +0100, Ingo Schwarze wrote: > As long as you only *use* macro packages, groff is *much* > easier to use than LaTeX (not least because the quality of > documentation of groff is vastly superior to LaTeX, and LaTeX > documentation is so extremely huge and fragmented that it's > a terrible challenge to find anything you need). > > But once you start modifying macro packages or writing your own > macros, i.e. once you enter into real programming, then it turns > out LaTeX is easier to program than roff(7) because the syntax and > semantics of the low-level roff(7) language are, let's put it > politely, quite unusual and surprising in many details. I know > that because i did write a non-trivial LaTeX module and because i > do maintain one of the larger roff macro packages, upstream at > groff, and besides, i did implement considerable parts of the roff > language in /usr/src/usr.bin/mandoc/roff.c. I actually wrote a semantic markup language shamelessly inspired from mdoc(7) and with simplified roff-like syntax, called “gofrundis” (actual tool is spelled frundis(1)), but primarily intented for authoring novels. It exports to LaTeX, HTML/EPUB or groff mom, and is documented using mdoc(7). That said, even though the language has quite silently existed for several years, excluding me it still has only two regular users as far as I know. The consequence is that there's not a community providing extension packages for it: anything not covered by the core language frundis_syntax(5) requires you to write some code in LaTeX, HTML or roff/mom and wrap it with macros. It's somewhat extensible, and I used it to write a thesis and export afterwards to LaTeX, because I find the syntax and semantics simpler and more pleasant to use. But I'm not sure I would recommend such non standard use. Yon
Re: Tools for writers
On Mon, Nov 04, 2019 at 02:27:38AM -0500, Steve Litt wrote: > I'm not sure, but I think if you write with a certain subset of TeX, it > would be fairly easy to write a program to convert it to XHTML5, from > which you can pretty easily create ePubs. Plain TeX as made by Knuth is > indeed simple for all simple things, and doable for more complicated > things. I do not think it's easy to define a subset of TeX and stick to it. I've used pandoc in the past to convert reasonably semantic LaTeX files to EPUB, and sticking to the right subset without accidentally using non supported commands was difficult at the time. Careful review of the produced EPUB was needed. Quite a nightmare. Thankfully, all of this ended the day I wasn't able anymore to compile pandoc and its hundred or so dependencies for OpenBSD :-) Maybe there are better TeX to EPUB tools now - I haven't tried combining tex4ht with calibre for a long time, for example. Using a presentational format like dvi as intermediate representation is a sign that TeX is unsuitable as a common source, but it may work well enough nevertheless. Otherwise, if both LaTeX and EPUB outputs are needed, and fine-grained control of the produced EPUB is wanted, using a well-defined intermediate markup language seems the safest way to go. Oddly enough for me, markdown still appears to be the most common choice. I would have thought that its caracteristics - semantically poor, with irregular and no-warnings “every text file accepted” permissive kind of syntax - would have made it unsuitable for maintaining long works. Yon
Re: Tools for writers
Hi, On Wed, Nov 06, 2019 at 08:43:18AM +0100, Ingo Schwarze wrote: > Hi Steve, > > Steve Litt wrote on Tue, Nov 05, 2019 at 06:38:52PM -0500: > > On Tue, 5 Nov 2019 18:38:03 +0100 > Ingo Schwarze wrote: > >> Andrew wrote on Sun, Nov 03, 2019 at 12:56:58PM +: > > >> [ Pandoc ] > >>> is one of the most useful tools I have ever used. If you are > >>> writing any sort of documentation then I *highly* recommend > >>> checking it out > > >> I strongly oppose that point. > > Admittedly, this was a bit of a diversion because the OP asked about > long, general-purpose texts like books - but all the same, it didn't > want to let the statement "pandoc is recommended for *documentation*" > go unchallenged. In my opinion, most of the points you made in the OpenBSD Journal apply for novels too, and probably even more so for technical books, but I can only judge for the first. The fact that markdown is not semantic, but essentially presentational, makes it impossible to make formatting changes to a whole semantic category after the fact (e.g. plant name, song title, place name), and impossible to automatically extract that information from the file for various purposes. A fully featured apropos(1) is not required for novels, but it's handy to at least be able to extract a list of names from a specific semantic category, whether to check it's correct, or to display it somewhere else (like an index). It's also handy when translating a work, to compare the original and translated version on specific points, often catching mistakes. But maybe the worst consequence of the markdown pitfalls you mention, is that it cannot provide any kind of syntax error reporting. Markup languages have different needs than programming languages. For example favouring warnings (like you did for mandoc(1)) is generally better than fatal errors (like often LaTeX). But no warnings (like markdown) is worse than both. Some people seem to think syntax highlighting is enough to avoid formatting mistakes, but you cannot depend on it when reading a diff, for example. And anyways, it's still easy to overlook a small formatting error. In my opinion, most of mandoc(1) design philosophy is worth considering for non-documentation long works: diff and grep-friendly simple non-ambiguous syntax, good non-fatal warnings, mostly semantic and fast. All of this seems good for any big project. When designing frundis(1) for novels, it's been my main inspiration, though it falls short on one point: due to the unpredictable requirements of creative works, it's been simpler (unavoidable?) to not make it fully self-contained. At least, new macros can abstract target format specific parts and make it fully-contained per project, which is still better than markdown. For long technical books, I don't think there's still anything approaching what mandoc(1) is for documentation. LaTeX and groff are good, but not semantic enough (making non-PDF exports tricky), have a quite fragile syntax at times and, in my experience, are not great at error reporting - which may be because of current tools instead of the languages themselves, though. Yon
Re: Tools for writers
On Tue, Nov 05, 2019 at 06:38:52PM -0500, Steve Litt wrote:
> > If you write documentation, just use the best format in the first
> > place. If the project you are documenting allows checking in
> > documentation in mdoc(7) format, use that.
>
> TL/DR SUMMARY: mdoc(7) is cool, but based on an hour or so's research is
> insufficient for all but the simplest full length books.
>
> I've spent the last hour or so looking at man pages mandoc(1) and
> mdoc(7), and I currently don't see how a non-simple book could be
> authored in mdoc(7). First of all, I see no method of creating a header
> hierarchy like ... or \part ... \subparagraph . I'd suspect it
> could be done by nesting .Sh lines, but I couldn't see how that could
> be done.
>
> As far as I can tell, mdoc(7) has no way to declare arbitrary styles.
> If I want a style called "stories", as an author I should be able to use
> one, and worry about semantic to presentational conversion of the
> stories style to be something I make later (with CSS or LaTeX or
> whatever). Almost by definition, if I can't create new semantic styles,
> I'll need to use or reuse predefined ones, which introduces ambiguity
> and mixing of semantic and presentational.
>
> Kudos for provisions to make a bibliography, and a TOC in HTML output.
>
> mdoc(7) supported lists cover a wide variety of presentations, but as
> far as I can tell you can't make new kinds of lists based on the
> existing lists. For instance, I might have a list for people with
> vertical spacing very different from a list for concepts, and I see no
> way to do that in mdoc(7) without declaring that all people are done
> with one kind of mdoc(7) list, and all concepts are done with another.
> Another problem: If I initially do both people and concepts with a
> certain mdoc(7) list type, and then decide people should look
> different, I'd have to search out all the people, instead of changing
> one line of CSS or one line of LaTeX.
Declaring arbitrary styles and semantics while being able to
produce HTML/EPUB and LaTeX was the main point of frundis.
I'll therefore provide some small examples, so that you may
research more if you want.
For example, you can define semantic tags for each format:
.X mtag -f latex -t people -c emph
.X mtag -f xhtml,epub -t people -c em
and then using them like:
.Sm -t people Steve
which will be rendered as Steve in
html, and \emph{Steve} in LaTeX.
There are different kind of semantic tags, whether for
phrasing elements or block/environment elements. The
language provides common semantic elements for novels (4
header levels, TOC, links, cross-references), but it lacks
more advanced functionality, like built-in bibliographies.
When built-in functionality is not enough, you can wrap
LaTeX and HTML code with macros. For example, you can write
the following macro hr in a file macros.frundis:
.#de hr \" define macro hr
.P
.Bf -f xhtml \" when exporting to HTML
.Ef
.Bf -f latex \" when exporting to LaTeX
\erule{\etextwidth}{1pt}
.Ef
.P
.#. \" end of definition
Then you can use it in your main file:
.If macros.frundis \" include macro definitions
.hr
If this kind of extensibility sounds like enough for what
you need, you may have a look at the whole mdoc(7) man page
frundis_syntax(5):
https://bardinflor.perso.aquilenet.fr/frundis/frundis_syntax-5.html
That said, if your books are too technical, you may end up
needing to extend yourself the language too much. Or maybe
you'll hit some unexpected limitations that will probably
not disappear with time, as the language is feature complete
for its main intended usage.
Yon
