~sircmpwn/public-inbox

4 3

[scdoc] proposals/discussion for adding new syntax

Details
Message ID
<CEQYYU3G24BA.1L0R8RE89BFJD@NotMyLaptop>
DKIM signature
missing
Download raw message
Looking through the tickets for scdoc, there are still some features
that would be useful that have not yet been implemented. To name a few:

- a mechanism to include other scdoc files [1]
- inline literal text (i.e. with backticks) [2]
- support for emails/hyperlinks [3]

[1]: https://todo.sr.ht/~sircmpwn/scdoc/24
[2]: https://todo.sr.ht/~sircmpwn/scdoc/6
[3]: https://todo.sr.ht/~sircmpwn/scdoc/25

I would like to help out with adding these. Inline literal text should
be relatively straightfoward: backticks can be used for that, as they
are in Markdown. However, I'd like to hear opinions on what the syntax
should be for the other constructs.

Specifically, it makes sense to try to avoid breaking existing scdoc
files as much as possible. Although scdoc doesn't explicitly claim to
be a stable format, it makes sense to try to keep things compatible,
since there are many projects which depend on scdoc. Hence, here are my
proposals:

For the include mechanism, I think it should look similar to the C
pre-processor: that is, the line starts with #include, followed by a
relative path to the file to include (quotes shouldn't be necessary). As
of now, starting a line with #include results in an error, since scdoc
expects the start of a heading, so this addition would be fully
backwards compatible.

Hyperlinks are trickier. Just wrapping the link in square brackets would
be nice, but I'd imagine square brackets are common enough in existing
scdoc files that this may be disruptive (hell, I used square brackets at
the beginning of this email). The best compromise I can think of is
using double square brackets instead, but I'm still unsure. What does
everyone else think?

Finally, I'd like to point out that although using backticks to denote
inline literal text is sensible, it is also a breaking change. The risk
is low, but there are some cases where backticks are used differently.
For example, it's not uncommon for identifiers/keywords to be wrapped
starting with a backtick and ending with a single quote (`like this').
In this case, I don't think that this is a big enough issue to warrant
rethinking the proposed backquote syntax, but it's worth bringing up.

Once a general consensus is reached, I'd be happy to contribute some
code.

- Sebastian
Details
Message ID
<CER9LHKR4E8V.TSLYZGUA6YP6@taiga>
In-Reply-To
<CEQYYU3G24BA.1L0R8RE89BFJD@NotMyLaptop> (view parent)
DKIM signature
missing
Download raw message
I'm inclined towards conservative improvements at this point. scdoc is
pretty stable and I think the current scope is just about right. Not
every feature which might be useful is worth having - the added
complexity comes with a cost which may not justify the utility.

On Tue Oct 5, 2021 at 12:17 AM CEST, Sebastian wrote:
> For the include mechanism, I think it should look similar to the C
> pre-processor: that is, the line starts with #include, followed by a
> relative path to the file to include (quotes shouldn't be necessary). As
> of now, starting a line with #include results in an error, since scdoc
> expects the start of a heading, so this addition would be fully
> backwards compatible.

I don't think that an include mechanism is desirable. What little text
is duplicated between man pages is generally very small and infrequently
updated, such as a footer with copyright information.

> Hyperlinks are trickier. Just wrapping the link in square brackets would
> be nice, but I'd imagine square brackets are common enough in existing
> scdoc files that this may be disruptive (hell, I used square brackets at
> the beginning of this email). The best compromise I can think of is
> using double square brackets instead, but I'm still unsure. What does
> everyone else think?

I don't think that the questions on this ticket have been adequately
answered. What practical utility does hyperlink support actually offer
given the current ecosystem of man implementations and terminal
emulators? Next to none, I think.

> Finally, I'd like to point out that although using backticks to denote
> inline literal text is sensible, it is also a breaking change. The risk
> is low, but there are some cases where backticks are used differently.
> For example, it's not uncommon for identifiers/keywords to be wrapped
> starting with a backtick and ending with a single quote (`like this').
> In this case, I don't think that this is a big enough issue to warrant
> rethinking the proposed backquote syntax, but it's worth bringing up.

I am more open to this idea than the others.
Details
Message ID
<CERQVLW85CNB.K2663TI00HP1@NotMyLaptop>
In-Reply-To
<CER9LHKR4E8V.TSLYZGUA6YP6@taiga> (view parent)
DKIM signature
missing
Download raw message
On October 5, 2021 2:37:36 AM EDT, Drew DeVault <sir@cmpwn.com> wrote:
> I'm inclined towards conservative improvements at this point. scdoc is
> pretty stable and I think the current scope is just about right. Not
> every feature which might be useful is worth having - the added
> complexity comes with a cost which may not justify the utility.

I agree, though I think that additions can be justified if they are both
useful and have a simple straightforward implementation.

> I don't think that an include mechanism is desirable. What little text
> is duplicated between man pages is generally very small and infrequently
> updated, such as a footer with copyright information.

That is true. In addition, an include mechanism would be non-trivial to
implement, with the good number of edge cases. Should includes be
handled before everything else is parsed, or with everything else? If
before, care has to be put in to ensure that includes don't expand
inside of pre-formatted (```) blocks. If they are handled with
everything else, then includes have to be handled in many different
contexts. Or maybe includes could only be permitted in certain
circumstances, to simplify implementation. Either way, work would have
to be done to keep track of line numbers and the original sources, for
legible error messages. In any case, trade-offs have to be made, and I
agree with you that the benefit does not outweigh the cost here.

> What practical utility does hyperlink support actually offer
> given the current ecosystem of man implementations and terminal
> emulators? Next to none, I think.

This prompted me to test the behavior of various popular terminal
emulators to see how they handled URLs ending in a trailing dot. In
almost every instance, the trailing dot was not included in the
clickable link. The one exception was Kitty, which only included the
trailing dot in the link if you hovered over said trailing dot, but
otherwise didn't include it. So given this, I'm inclined to agree with
you that hyperlinks aren't necessary to support. The ticket should
probably be closed in that case (same with the "include" ticket).

> I am more open to this idea [backticks for inline text] than the others.

I agree; this seems like a relatively simple feature that would be both
useful and simple to implement. There is one detail to work out, though:
in Markdown, inline literal text can be surrounded by any number of
backticks. So `this` is valid, and so is ``this``. The latter allows for
a single backtick to be embedded inside the literal text;
``something like ` this``. Is such a feature worth implementing in
scdoc? One part of me wants to say no, to simplify the implementation.
But this is the only way I can think of to allow literal backticks
inside the text, so it may be necessary if that is desirable.

- Sebastian
Details
Message ID
<CES3U3BAZPAP.41DM4GN0DZV4@taiga>
In-Reply-To
<CERQVLW85CNB.K2663TI00HP1@NotMyLaptop> (view parent)
DKIM signature
missing
Download raw message
On Tue Oct 5, 2021 at 10:10 PM CEST, Sebastian wrote:
> I agree, though I think that additions can be justified if they are both
> useful and have a simple straightforward implementation.

The other constraint is that their utility has to be measured against
the increase in complexity they add to scdoc as a whole. A project made
of 100 simple features is not a simple project. The problem is in
knowing which features are worth the tradeoff.

> I agree; this seems like a relatively simple feature that would be both
> useful and simple to implement. There is one detail to work out, though:
> in Markdown, inline literal text can be surrounded by any number of
> backticks. So `this` is valid, and so is ``this``. The latter allows for
> a single backtick to be embedded inside the literal text;
> ``something like ` this``. Is such a feature worth implementing in
> scdoc? One part of me wants to say no, to simplify the implementation.
> But this is the only way I can think of to allow literal backticks
> inside the text, so it may be necessary if that is desirable.

I have no strong opinions, either we could use `...` and prohibit
backticks or we could implement ``..`..``. Both seem equally reasonable.
Details
Message ID
<bef078289ccade1e511b52550fbe6388dd4d2bc6.camel@ianmjones.com>
In-Reply-To
<CES3U3BAZPAP.41DM4GN0DZV4@taiga> (view parent)
DKIM signature
missing
Download raw message
On Wed, 2021-10-06 at 08:19 +0200, Drew DeVault wrote:
> On Tue Oct 5, 2021 at 10:10 PM CEST, Sebastian wrote:
> > There is one detail to work out though:
> > in Markdown, inline literal text can be surrounded by any number of
> > backticks. So `this` is valid, and so is ``this``. The latter
> > allows for
> > a single backtick to be embedded inside the literal text;
> > ``something like ` this``. Is such a feature worth implementing in
> > scdoc? One part of me wants to say no, to simplify the
> > implementation.
> > But this is the only way I can think of to allow literal backticks
> > inside the text, so it may be necessary if that is desirable.
> 
> I have no strong opinions, either we could use `...` and prohibit
> backticks or we could implement ``..`..``. Both seem equally
> reasonable.

It would be useful to me if backticks were allowed in inline code
segments.

In the man page for Snippet Pixie I needed to mention the default
keystroke of Ctrl+`, and would prefer to have had it formatted as code.
At the moment I'm using *Ctrl*+*`* where I want the individual keys to
be clear. In other places the backtick is part of a string, so I can
get away with things like "sp`", but would prefer to have that
formatted as a single code segment.

I would be happy to escape the backtick literal, so `Ctrl`+`\`` would
be fine, as would `sp\``.

The ``..`` format seems like it might open up a can of worms.

Ian
Reply to thread Export thread (mbox)