reviving an old suggestion about YP docs markup

reviving an old suggestion about YP docs markup

[rpjday]

  with the recent loss of scott rifenbark, since i used to be fairly
active in working on the docs, i figure it's time to get off my a**
and get involved again and contribute. to that end, i once made a
suggestion about being more precise about the docbook markup being
used in the YP manuals.

  in many cases, a number of types of entities in the docs are marked
up simply as <filename> which, when generating HTML, renders as
simple italics. so in cases like generating HTML, there's no
difference in whether the entity being marked up is actually a
filename, or a command, or something just being emphasized, and so on.
but when one thinks of generating more refined output (PDF, for
example), it would be useful if those entities really had the
potential to be rendered differently. here are some examples.

  first, yes, if something is a filename, then <filename> is the
obvious markup.

  on the other hand, variables should properly be marked up as
<variable>, which they currently aren't. a good example is in the
reference manual, the variables, where glossary definitions all use
the <filename> markup for variables. again, it may make no difference
in the ultimate rendering to something as trivial as HTML but, some
day, it will be useful to be able to render things differently
depending on the choice of output.

  options should be tagged as <option>, which actually does look nicer
even in HTML output; at the moment, most options are simply quoted, as
in:

    To ensure consistent behavior, BitBake's "-r" and "-R" ...

  another woefully underused tag is <firstitem>, meant to emphasize
the first time a term is being used to grab the reader's attention.
again, for HTML, that renders simply as italics, but who knows what
might happen in the future. also, using the <firstterm> tag provides a
simple way to collect all such expressions in the docs, perhaps for
index generation.

  a final example is command markup, which ideally would use the
<command> tag. i tested that and, in the current doc processing
toolchain, it shows up in HTML as a fairly aggressive bolding. but
even if that seems unsightly, the proper approach would be to use
proper markup, then tweak the stylesheets to define how it *should* be
rendered.

  obviously, this is not a high priority as the docs are in great
shape as it is, but i think at some point it would be useful to start
using appropriate markup, and adjust the backend XSL stylesheets to
define the rendering.

  thoughts?

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                         http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: [yocto] reviving an old suggestion about YP docs markup

[Ross Burton]

On Tue, 11 Feb 2020 at 11:13, rpjday@crashcourse.ca
<rpjday@crashcourse.ca> wrote:
>   first, yes, if something is a filename, then <filename> is the
> obvious markup.
>
>   on the other hand, variables should properly be marked up as
> <variable>, which they currently aren't. a good example is in the
> reference manual, the variables, where glossary definitions all use
> the <filename> markup for variables. again, it may make no difference
> in the ultimate rendering to something as trivial as HTML but, some
> day, it will be useful to be able to render things differently
> depending on the choice of output.

I'd say fine, patches welcome. Maybe Scott chose a subset of Docbook
to ease the formatting?  Either way, I can't see a good argument
*against* using a broader set of tags.  At some point you could have
some lint tooling to verify that every <variable> is in the variable
index, for example.

Ross

Re: [yocto] reviving an old suggestion about YP docs markup

[rpjday]

On Tue, 11 Feb 2020, Ross Burton wrote:

> On Tue, 11 Feb 2020 at 11:13, rpjday@crashcourse.ca
> <rpjday@crashcourse.ca> wrote:
> >   first, yes, if something is a filename, then <filename> is the
> > obvious markup.
> >
> >   on the other hand, variables should properly be marked up as
> > <variable>, which they currently aren't. a good example is in the
> > reference manual, the variables, where glossary definitions all
> > use the <filename> markup for variables. again, it may make no
> > difference in the ultimate rendering to something as trivial as
> > HTML but, some day, it will be useful to be able to render things
> > differently depending on the choice of output.
>
> I'd say fine, patches welcome. Maybe Scott chose a subset of Docbook
> to ease the formatting?  Either way, I can't see a good argument
> *against* using a broader set of tags.  At some point you could have
> some lint tooling to verify that every <variable> is in the variable
> index, for example.

  yes, that's along the lines of using <firstterm> when appropriate.
i'm not suggesting trying to dig into every corner of docbook, just
the judicious usage of the most obvious tags. i'll do some research to
see what minimum set of tags would make sense. as a start, probably:

  * <filename>
  * <variable>
  * <command>
  * <option>
  * <firstterm>

all strike me as obvious (in addition to what's already used).

rday

Re: [yocto] reviving an old suggestion about YP docs markup

[Ross Burton]

My problem with <firstterm> is that you need to keep on reviewing to
verify it is the first usage.  Better to post-process that, surely.

Ross

On Tue, 11 Feb 2020 at 14:35, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
>
> On Tue, 11 Feb 2020, Ross Burton wrote:
>
> > On Tue, 11 Feb 2020 at 11:13, rpjday@crashcourse.ca
> > <rpjday@crashcourse.ca> wrote:
> > >   first, yes, if something is a filename, then <filename> is the
> > > obvious markup.
> > >
> > >   on the other hand, variables should properly be marked up as
> > > <variable>, which they currently aren't. a good example is in the
> > > reference manual, the variables, where glossary definitions all
> > > use the <filename> markup for variables. again, it may make no
> > > difference in the ultimate rendering to something as trivial as
> > > HTML but, some day, it will be useful to be able to render things
> > > differently depending on the choice of output.
> >
> > I'd say fine, patches welcome. Maybe Scott chose a subset of Docbook
> > to ease the formatting?  Either way, I can't see a good argument
> > *against* using a broader set of tags.  At some point you could have
> > some lint tooling to verify that every <variable> is in the variable
> > index, for example.
>
>   yes, that's along the lines of using <firstterm> when appropriate.
> i'm not suggesting trying to dig into every corner of docbook, just
> the judicious usage of the most obvious tags. i'll do some research to
> see what minimum set of tags would make sense. as a start, probably:
>
>   * <filename>
>   * <variable>
>   * <command>
>   * <option>
>   * <firstterm>
>
> all strike me as obvious (in addition to what's already used).
>
> rday

Re: [yocto] reviving an old suggestion about YP docs markup

[rpjday]

On Tue, 11 Feb 2020, Ross Burton wrote:

> My problem with <firstterm> is that you need to keep on reviewing to
> verify it is the first usage.  Better to post-process that, surely.

  but that's not the way it's normally used ... <firstterm> doesn't
necessarily mean the physically first time a term is used, it's more
typically used to identify where the term is formally introduced and
explained to the reader.

  for example, there's nothing wrong with using, say, "BSP layer"
early in a manual as part of a list of YP components or something, but
<firstterm> would be used when the manual finally got around to
explaining the term. that's why <firstterm> is frequently used for
index generation; because that's where the reader should go for the
*explanation* of the term, not just its first physical occurrence.

rday

Re: [yocto] reviving an old suggestion about YP docs markup

[Ross Burton]

Ah gotcha.  My docbook-fu is somewhat hazy.

Yes, seems sensible.

Ross

On Tue, 11 Feb 2020 at 14:43, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
>
> On Tue, 11 Feb 2020, Ross Burton wrote:
>
> > My problem with <firstterm> is that you need to keep on reviewing to
> > verify it is the first usage.  Better to post-process that, surely.
>
>   but that's not the way it's normally used ... <firstterm> doesn't
> necessarily mean the physically first time a term is used, it's more
> typically used to identify where the term is formally introduced and
> explained to the reader.
>
>   for example, there's nothing wrong with using, say, "BSP layer"
> early in a manual as part of a list of YP components or something, but
> <firstterm> would be used when the manual finally got around to
> explaining the term. that's why <firstterm> is frequently used for
> index generation; because that's where the reader should go for the
> *explanation* of the term, not just its first physical occurrence.
>
> rday

Re: [yocto] reviving an old suggestion about YP docs markup

[rpjday]

On Tue, 11 Feb 2020, Ross Burton wrote:

> Ah gotcha.  My docbook-fu is somewhat hazy.
>
> Yes, seems sensible.
>
> Ross
>
> On Tue, 11 Feb 2020 at 14:43, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
> >
> > On Tue, 11 Feb 2020, Ross Burton wrote:
> >
> > > My problem with <firstterm> is that you need to keep on reviewing to
> > > verify it is the first usage.  Better to post-process that, surely.
> >
> >   but that's not the way it's normally used ... <firstterm> doesn't
> > necessarily mean the physically first time a term is used, it's more
> > typically used to identify where the term is formally introduced and
> > explained to the reader.
> >
> >   for example, there's nothing wrong with using, say, "BSP layer"
> > early in a manual as part of a list of YP components or something, but
> > <firstterm> would be used when the manual finally got around to
> > explaining the term. that's why <firstterm> is frequently used for
> > index generation; because that's where the reader should go for the
> > *explanation* of the term, not just its first physical occurrence.

  heh ... i remember it took me a few reads once upon a time to
finally grok the proper usage of a lot of docbook markup. in any
event, i'm not pushing for a bunch of stuff to happen all at once, i'm
just going to collect ideas for future work.

  first thought (as i whined about already) is to start using at least
a minimal set of more appropriate markup (<variable>, <command>,
<option>, <firstterm> and so on).

  following on that, it's inevitable that, even when the markup is
appropriate, the rendering might not be ideal, so start tweaking XSL
stylesheets to change that rendering as needed.

  in addition, depending on need, perhaps invent new markup (although
this is pretty extreme given that docbook should support almost every
type of markup imaginable).

  finally (and really long term), maybe move to docbook 5 and Relax
NG, but that would be a long way off if it even happens at all.

  anyway, i'll just put these ideas aside for now.

rday

p.s. one fairly obvious improvement would be to define the proper
rendering of code or command-line snippets. right now, as i read it,
command examples are marked up with:

                <literallayout class='monospaced'>
     $ bitbake -h
     $ bitbake --help
                </literallayout>


which is kind of cumbersome and requires the author to add the proper
leading spaces for rendering. i'm fairly sure XSL can make that
simpler so that arbitrary indentation is processed properly. again, a
long term idea.