discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: Stephen Gregoratto <dev@sgregoratto.me>
Cc: discuss@mandoc.bsd.lv
Subject: Re: scdoc2mdoc - Alpha release and a call for help
Date: Sat, 6 Jul 2019 17:32:08 +0200	[thread overview]
Message-ID: <20190706153208.GD98610@athene.usta.de> (raw)
In-Reply-To: <20190705034415.iu7gl7ad4mjjxgic@BlackBox>

Hi Stephen,

Stephen Gregoratto wrote on Fri, Jul 05, 2019 at 01:44:15PM +1000:

> Last month I talked about up scdoc, a program that converts a
> Markdown-style presentational markup to man(7). I talked to the creator
> about rewriting it to output mdoc(7) instead,

That's a terrible idea.  If upstream is willing to use a good markup
language, they should maintain their documentation directly in
mdoc(7).  That results in great markup power while keeping the
documents easy to maintain.

When they insist on using a bad language for maintaining their
documents (like Markdown or DocBook), converting such bad input
into mdoc(7) will not help much.  The markup power of the result
will still be poor, and the the documentation will still be painful
to maintain given the poor source language.

> but he explicitly didn't
> want that. So, I've decided to fork[1] it.
[...]
> - Tables in scdoc are set out cell-by-cell, one per line. You can also
>   change the text alignment for each cell (why you'd want to in a
>   manpage I wouldn't know). Currently, the program reads the table
>   completely and allocates a linked-list of rows, which then contain a
>   linked list of cells. At the end of parsing, the program spits out the
>   appropriate tbl(7) representation, printing the alignment for each
>   cell (even if they don't change) and wrapping each cell in a "T{ ...
>   }T" block. This is done in the parse_table() function.
> 
>   I'd like to rewrite this to output this as a .Bl -column list,

Why?

The .Bl -column does not have more semantic markup power than tbl(7).

If the document as a whole is written in mdoc(7), then using
.Bl -column is more portable and robust than using tbl(7).

But when the overall document quality is very poor in the first
place - which it will unavoidably always be when starting from
some Markdown variant - then such minor benefits in robustness
are irrelevant; the whole thing will always be somewhat fragile
either way.

My suggestion would be to save yourself the work and just stick
to the tbl(7) code you already have.

> - Bold and italic text are formatted using the \fB/\fI escapes
>   (parse_format()). I'll have to change this to keep track of the
>   current text "format" and print a "Sy/Em" for each new line.

Why?

The macros .Sy and .Em have almost no semantic power, they are
explicitly documented as "physical markup".

Of course, if you write a manual page by hand, don't use font
escapes.  But that hardly applies to an automatic converter.

If you could guess with heuristics (like pod2mdoc(1) does)
which semantic macro to use, *that* would be a real improvement,
but .Sy and .Em don't reach that goal.

If your point were to help half-automatic, half-manual upgrades
from Markdown to mdoc(7) for the result to be maintained afterwards
and the original input discarded, writing .Sy and .Em might make
sense because they are easier to replace manually by the correct
macros.  But when manual postprocessing is not intended and the
original Markdown documents keep being maintained, what's the point
in writing .Sy and .Em?

> Even though I understand these problems, I don't feel that I have the
> technical ability to solve them effectively, which is why I've come here
> for help.

I hope you find help.

Myself, i might look at some point, but not right now, so don't
hold your breath.

If the project comes close to being usable in practice, i shall
list it on the mandoc.bsd.lv frontpage (like docbook2mdoc).
If i forget, poke me when you think it is usable, at the
latest when you make a release.

[...]
> As for why I'm doing this, there is one big reason. The creator of scdoc
> also maintains a popular Wayland compositor library (wlroots) and the
> most popular Wayland compositor behind GNOME and KDE (sway). He's
> considered a major developer in Wayland development circles. He also
> enforces the use of scdoc for every new project he makes.

Yikes.

> The result: many other Wayland projects are starting to use scdoc
> for their manpages because of this influence.
> 
> Eventually when Wayland compositors/programs will be ported to OpenBSD,
> scdoc is going to be included. My hope is to "fix" scdoc to output in a
> sane markup language suitable for OpenBSD, similar to pod/docbook2mdoc.

That might make sense, for similar reasons as Xenocara uses docbook2mdoc.

For now, even if Wayland uses it, scdoc appears to be even more of
a niche product than DocBook, and let's really hope that it will
never become widespread.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

      reply	other threads:[~2019-07-06 15:32 UTC|newest]

Thread overview: 2+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-07-05  3:44 Stephen Gregoratto
2019-07-06 15:32 ` Ingo Schwarze [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190706153208.GD98610@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=dev@sgregoratto.me \
    --cc=discuss@mandoc.bsd.lv \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).