[m-dev.] Markup in User's guide

[Julien Fischer]

On Thu, 17 Jul 2025 at 16:50, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
>
>
>
> On Thu, 17 Jul 2025 16:36:07 +1000, Julien Fischer <jfischer at opturion.com> wrote:
> > When marking up the names of programs or scripts (e.g. mmc, mgnuc
> > etc.) in the user's guide, we seem to use an inconsistent mixture of
> > @samp and @code. Both format their contents using a fixed-width font,
> > but the former adds single quotes, while the latter does not.
> >
> > I think we should settle on one or the other; my preference would be
> > for @command
> > (which is equivalent to @code).
>
> I noticed that too, and intended to bring it up once I was done with my
> changes to the user guide. There is a good reason to switch away from @samp
> even apart from the inconsistency, which is that more than once, we have text
> such as "@samp{xyz}'s something", and the quotes added by @samp look really
> strange next to the quotes indicating "possessive voice".
>
> In addition, @samp seems to format its argument in a smaller font than nearby text
> for me, though that may just be my browser's setup.

I haven't noticed it in a browser, however it looks particularly silly
in the PDF version.

I would note that a similar inconsistency occurs for environment
variables, where we
use all of @samp, @code and @env with them.

> I am not sure about moving to @command as opposed to @code. If they are equivalent,
> then we can *try* to we maintain a distinction in the .texi file, but deviations won't be
> reflected in the output, so they will be harder to notice.

texinfo provides both @command and @option; while they current texinfo
processors
seem to treat them equivalently to @code, there's no reason that they
have to do that.

> Also, please don't make any changes to user_guide.texi until I am done, since
> they are very likely to cause conflicts.

Ok.

Julien.