what's the standard for em dashes in sphinx for YP docs?

what's the standard for em dashes in sphinx for YP docs?

[Robert P. J. Day]

  i want to play with sentence structure, and in some places, the "em"
dash is clearly appropriate. apparently, a triple "---" renders nicely
into a long dash. is that the standard?

rday

Re: [docs] what's the standard for em dashes in sphinx for YP docs?

[Quentin Schulz]

Hi Robert,

On Sat, Aug 28, 2021 at 12:08:34PM -0400, Robert P. J. Day wrote:
> 
>   i want to play with sentence structure, and in some places, the "em"
> dash is clearly appropriate. apparently, a triple "---" renders nicely
> into a long dash. is that the standard?
> 

The only issue I could see with using "em" dashes is that it makes it
harder to grep for them.

Also, we'll probably forget to enforce this in future patches :)

I don't have much more to add to the discussion though.

Cheers,
Quentin

Re: [docs] what's the standard for em dashes in sphinx for YP docs?

[Robert P. J. Day]

On Mon, 30 Aug 2021, Quentin Schulz wrote:

> Hi Robert,
>
> On Sat, Aug 28, 2021 at 12:08:34PM -0400, Robert P. J. Day wrote:
> >
> >   i want to play with sentence structure, and in some places, the "em"
> > dash is clearly appropriate. apparently, a triple "---" renders nicely
> > into a long dash. is that the standard?
> >
>
> The only issue I could see with using "em" dashes is that it makes it
> harder to grep for them.
>
> Also, we'll probably forget to enforce this in future patches :)
>
> I don't have much more to add to the discussion though.

  yeah, the instant i used a grep, i realized the worm can i was
opening up.

rday

Re: [docs] what's the standard for em dashes in sphinx for YP docs?

[Michael Opdenacker]

Hello,

On 8/30/21 10:12 AM, Robert P. J. Day wrote:
> On Mon, 30 Aug 2021, Quentin Schulz wrote:
>
>> Hi Robert,
>>
>> On Sat, Aug 28, 2021 at 12:08:34PM -0400, Robert P. J. Day wrote:
>>>   i want to play with sentence structure, and in some places, the "em"
>>> dash is clearly appropriate. apparently, a triple "---" renders nicely
>>> into a long dash. is that the standard?
>>>
>> The only issue I could see with using "em" dashes is that it makes it
>> harder to grep for them.
>>
>> Also, we'll probably forget to enforce this in future patches :)
>>
>> I don't have much more to add to the discussion though.
>   yeah, the instant i used a grep, i realized the worm can i was
> opening up.


Indeed (because of the use of "-" and "=" in styling paragraphs)!
However, that's still possible to catch unique instances of "---":
git grep -E "[^-](\-){3}[^-]"

After reading https://www.scribbr.com/language-rules/dashes/, it seems
to me that proper dashes ("--" for "en dashes" and "---" for "em
dashes") should still be used in proper documentation.

What would be the drawback of using those? Even if "---" and "--" alone
are a bit hard to grep, what else would they make harder to process?

Cheers,
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] what's the standard for em dashes in sphinx for YP docs?

[Robert P. J. Day]

On Mon, 30 Aug 2021, Michael Opdenacker wrote:

> Hello,
>
> On 8/30/21 10:12 AM, Robert P. J. Day wrote:
> > On Mon, 30 Aug 2021, Quentin Schulz wrote:
> >
> >> Hi Robert,
> >>
> >> On Sat, Aug 28, 2021 at 12:08:34PM -0400, Robert P. J. Day wrote:
> >>>   i want to play with sentence structure, and in some places, the "em"
> >>> dash is clearly appropriate. apparently, a triple "---" renders nicely
> >>> into a long dash. is that the standard?
> >>>
> >> The only issue I could see with using "em" dashes is that it makes it
> >> harder to grep for them.
> >>
> >> Also, we'll probably forget to enforce this in future patches :)
> >>
> >> I don't have much more to add to the discussion though.
> >   yeah, the instant i used a grep, i realized the worm can i was
> > opening up.
>
>
> Indeed (because of the use of "-" and "=" in styling paragraphs)!
> However, that's still possible to catch unique instances of "---":
> git grep -E "[^-](\-){3}[^-]"
>
> After reading https://www.scribbr.com/language-rules/dashes/, it
> seems to me that proper dashes ("--" for "en dashes" and "---" for
> "em dashes") should still be used in proper documentation.
>
> What would be the drawback of using those? Even if "---" and "--"
> alone are a bit hard to grep, what else would they make harder to
> process?

  i will go with the consensus -- i asked only because there are
always places where one would properly use a comma, and others a
semi-colon, and others an em dash, and so on. (see what i did there?)

rday

Re: [docs] what's the standard for em dashes in sphinx for YP docs?

[Michael Opdenacker]

On 8/30/21 2:54 PM, Robert P. J. Day wrote:
>
>   i will go with the consensus -- i asked only because there are
> always places where one would properly use a comma, and others a
> semi-colon, and others an em dash, and so on. (see what i did there?)


:D

Right, I believe we should follow the rules rather than inventing new
ones or having none.

So, I'll vote for the proper use of "--" (en dash) and "---" (em dash)
when suitable, and document this in the coding style I need to propose.
Any objections?

Cheers,

Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com