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 <h1>...<h6> 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 <em class="people">Steve</em> 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
<hr>
.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
