rendering double dashes more emphatically

rendering double dashes more emphatically

[Robert P. J. Day]

  reading bitbake user manual and, in section 1.5.2.2:

https://docs.yoctoproject.org/bitbake/bitbake-user-manual/bitbake-user-manual-intro.html#executing-tasks-against-a-set-of-recipe-files

in the first line of the second paragraph, the distinction between a
single dash and a double dash seems to be pretty vague since, by
default, i believe sphinx renders a double dash as simply an "em", so
visually, it's just not as clear as it could be.

one possible fix is to mark up stuff like that with ``...``, since it
seems it should be monospaced content anyway, and doing that renders
double dashes nicely.

  thoughts? other options?

rday

Re: [docs] rendering double dashes more emphatically

[Quentin Schulz]

Hi Robert,

On Tue, Mar 09, 2021 at 04:58:54AM -0500, Robert P. J. Day wrote:
> 
>   reading bitbake user manual and, in section 1.5.2.2:
> 
> https://docs.yoctoproject.org/bitbake/bitbake-user-manual/bitbake-user-manual-intro.html#executing-tasks-against-a-set-of-recipe-files
> 
> in the first line of the second paragraph, the distinction between a
> single dash and a double dash seems to be pretty vague since, by
> default, i believe sphinx renders a double dash as simply an "em", so
> visually, it's just not as clear as it could be.
> 
> one possible fix is to mark up stuff like that with ``...``, since it
> seems it should be monospaced content anyway, and doing that renders
> double dashes nicely.
> 
>   thoughts? other options?
> 

Considering in Yocto docs we usually use ``--options`` when not in
code-blocks, I'd say it's pretty safe to do the same for bitbake
documentation.

FWIW, I (or anyone else?) haven't gone through bitbake documentation
since the move to sphinx to fix the leftover of the migration. Heck, I
haven't even finished Yocto's one :/

Please send a patch :)

Thanks,
Quentin

Re: [docs] rendering double dashes more emphatically

[Robert P. J. Day]

On Tue, 9 Mar 2021, Quentin Schulz wrote:

> Hi Robert,
>
> On Tue, Mar 09, 2021 at 04:58:54AM -0500, Robert P. J. Day wrote:
> >
> >   reading bitbake user manual and, in section 1.5.2.2:
> >
> > https://docs.yoctoproject.org/bitbake/bitbake-user-manual/bitbake-user-manual-intro.html#executing-tasks-against-a-set-of-recipe-files
> >
> > in the first line of the second paragraph, the distinction between a
> > single dash and a double dash seems to be pretty vague since, by
> > default, i believe sphinx renders a double dash as simply an "em", so
> > visually, it's just not as clear as it could be.
> >
> > one possible fix is to mark up stuff like that with ``...``, since it
> > seems it should be monospaced content anyway, and doing that renders
> > double dashes nicely.
> >
> >   thoughts? other options?
> >
>
> Considering in Yocto docs we usually use ``--options`` when not in
> code-blocks, I'd say it's pretty safe to do the same for bitbake
> documentation.
>
> FWIW, I (or anyone else?) haven't gone through bitbake documentation
> since the move to sphinx to fix the leftover of the migration. Heck, I
> haven't even finished Yocto's one :/
>
> Please send a patch :)

  last question -- should patches to BB manual be sent to the YP docs
list, or to the bitbake-devel list, since BB docs are part of the BB
checkout?

rday

Re: [docs] rendering double dashes more emphatically

[Quentin Schulz]

On Tue, Mar 09, 2021 at 05:27:31AM -0500, Robert P. J. Day wrote:
> On Tue, 9 Mar 2021, Quentin Schulz wrote:
> 
> > Hi Robert,
> >
> > On Tue, Mar 09, 2021 at 04:58:54AM -0500, Robert P. J. Day wrote:
> > >
> > >   reading bitbake user manual and, in section 1.5.2.2:
> > >
> > > https://docs.yoctoproject.org/bitbake/bitbake-user-manual/bitbake-user-manual-intro.html#executing-tasks-against-a-set-of-recipe-files
> > >
> > > in the first line of the second paragraph, the distinction between a
> > > single dash and a double dash seems to be pretty vague since, by
> > > default, i believe sphinx renders a double dash as simply an "em", so
> > > visually, it's just not as clear as it could be.
> > >
> > > one possible fix is to mark up stuff like that with ``...``, since it
> > > seems it should be monospaced content anyway, and doing that renders
> > > double dashes nicely.
> > >
> > >   thoughts? other options?
> > >
> >
> > Considering in Yocto docs we usually use ``--options`` when not in
> > code-blocks, I'd say it's pretty safe to do the same for bitbake
> > documentation.
> >
> > FWIW, I (or anyone else?) haven't gone through bitbake documentation
> > since the move to sphinx to fix the leftover of the migration. Heck, I
> > haven't even finished Yocto's one :/
> >
> > Please send a patch :)
> 
>   last question -- should patches to BB manual be sent to the YP docs
> list, or to the bitbake-devel list, since BB docs are part of the BB
> checkout?
> 

I don't remember seeing patches for bitbake docs in my mailbox. I'm not
subscribed to bitbake-devel ML, so I'd guess you should send to
bitbake-devel :)

Send a patch and people will tell you anyway :)

Cheers,
Quentin

Re: [docs] rendering double dashes more emphatically

[Nicolas Dechesne]

On Tue, Mar 9, 2021 at 11:31 AM Quentin Schulz
<quentin.schulz@streamunlimited.com> wrote:
>
> On Tue, Mar 09, 2021 at 05:27:31AM -0500, Robert P. J. Day wrote:
> > On Tue, 9 Mar 2021, Quentin Schulz wrote:
> >
> > > Hi Robert,
> > >
> > > On Tue, Mar 09, 2021 at 04:58:54AM -0500, Robert P. J. Day wrote:
> > > >
> > > >   reading bitbake user manual and, in section 1.5.2.2:
> > > >
> > > > https://docs.yoctoproject.org/bitbake/bitbake-user-manual/bitbake-user-manual-intro.html#executing-tasks-against-a-set-of-recipe-files
> > > >
> > > > in the first line of the second paragraph, the distinction between a
> > > > single dash and a double dash seems to be pretty vague since, by
> > > > default, i believe sphinx renders a double dash as simply an "em", so
> > > > visually, it's just not as clear as it could be.
> > > >
> > > > one possible fix is to mark up stuff like that with ``...``, since it
> > > > seems it should be monospaced content anyway, and doing that renders
> > > > double dashes nicely.
> > > >
> > > >   thoughts? other options?
> > > >
> > >
> > > Considering in Yocto docs we usually use ``--options`` when not in
> > > code-blocks, I'd say it's pretty safe to do the same for bitbake
> > > documentation.
> > >
> > > FWIW, I (or anyone else?) haven't gone through bitbake documentation
> > > since the move to sphinx to fix the leftover of the migration. Heck, I
> > > haven't even finished Yocto's one :/
> > >
> > > Please send a patch :)
> >
> >   last question -- should patches to BB manual be sent to the YP docs
> > list, or to the bitbake-devel list, since BB docs are part of the BB
> > checkout?
> >
>
> I don't remember seeing patches for bitbake docs in my mailbox. I'm not
> subscribed to bitbake-devel ML, so I'd guess you should send to
> bitbake-devel :)
>
> Send a patch and people will tell you anyway :)

It's bitbake-devel for bitbake. Though I wouldn't be against sending
to yocto-docs as well to get more visibility from our sphinx local
experts!
Richard?

>
> Cheers,
> Quentin
>
> 
>

Re: [docs] rendering double dashes more emphatically

[Robert P. J. Day]

On Tue, 9 Mar 2021, Quentin Schulz wrote:

> Hi Robert,
>
> On Tue, Mar 09, 2021 at 04:58:54AM -0500, Robert P. J. Day wrote:
> >
> >   reading bitbake user manual and, in section 1.5.2.2:
> >
> > https://docs.yoctoproject.org/bitbake/bitbake-user-manual/bitbake-user-manual-intro.html#executing-tasks-against-a-set-of-recipe-files
> >
> > in the first line of the second paragraph, the distinction between a
> > single dash and a double dash seems to be pretty vague since, by
> > default, i believe sphinx renders a double dash as simply an "em", so
> > visually, it's just not as clear as it could be.
> >
> > one possible fix is to mark up stuff like that with ``...``, since it
> > seems it should be monospaced content anyway, and doing that renders
> > double dashes nicely.
> >
> >   thoughts? other options?
> >
>
> Considering in Yocto docs we usually use ``--options`` when not in
> code-blocks, I'd say it's pretty safe to do the same for bitbake
> documentation.

  last, really, really, nitpicky question about this rendering ... if
one renders in monospace, is it worth still surrounding that with
double quotes? since there is an erratic mixture of those two styles.
as in:

  You can use the --c option to ...

versus

  You can use the "--c" option to ...

Personally, I'd forego the quotes, but ... thoughts? Just trying to
get a consistent feel for the rendering.

rday

p.s. also personally, for verbatim/monospaced rendering, i might pick
a font that's not so visually similar to the regular text as it's
rendered, at least in my browser.

Re: [docs] rendering double dashes more emphatically

[Richard Purdie]

On Tue, 2021-03-09 at 12:00 +0100, Nicolas Dechesne wrote:
> On Tue, Mar 9, 2021 at 11:31 AM Quentin Schulz
> <quentin.schulz@streamunlimited.com> wrote:
> > 
> > 
> > I don't remember seeing patches for bitbake docs in my mailbox. I'm not
> > subscribed to bitbake-devel ML, so I'd guess you should send to
> > bitbake-devel :)
> > 
> > Send a patch and people will tell you anyway :)
> 
> It's bitbake-devel for bitbake. Though I wouldn't be against sending
> to yocto-docs as well to get more visibility from our sphinx local
> experts!
> Richard?

Technically it is bitbake-devel as the docs are in bitbake's repo but sending
to both might not be a bad idea even if it is cross posting.

Cheers,

Richard