Manual consistency

Manual consistency

[zimoun]

Hi Ludo,

(from: http://issues.guix.gnu.org/issue/41253#10)

On Fri, 5 Jun 2020 at 18:36, Ludovic Courtès <ludo@gnu.org> wrote:

> > There are many examples in guix.texi with $, and also many without. Plus
> > some with # as the command line prompt.
>
> Yeah, the manual is kinda inconsistent, and I’m self-inconsistent to
> tell the truth.  :-)
>
> I’ve come to the conclusion that snippets that contain only input should
> be written without a prompt, for easier copy/pasting.
>
> (I’ve seen Python documentation where JS magic allows people to toggle
> prompt display, I find it nice.)

I propose to do a pass on that:
 - apply this rule: no-$ for only input and $ to distinguish between
inputs and outputs.
 - backtick ` replaced by $(...) as discussed elsewhere
and then send a "Fix typo" patch.  And maybe add a bullet in the
Contributing Section.

WDYT?

All the best,
simon

Re: Manual consistency

[Julien Lepiller]

Le 5 juin 2020 13:34:57 GMT-04:00, zimoun <zimon.toutoune@gmail.com> a écrit :
>Hi Ludo,
>
>(from: http://issues.guix.gnu.org/issue/41253#10)
>
>On Fri, 5 Jun 2020 at 18:36, Ludovic Courtès <ludo@gnu.org> wrote:
>
>> > There are many examples in guix.texi with $, and also many without.
>Plus
>> > some with # as the command line prompt.
>>
>> Yeah, the manual is kinda inconsistent, and I’m self-inconsistent to
>> tell the truth.  :-)
>>
>> I’ve come to the conclusion that snippets that contain only input
>should
>> be written without a prompt, for easier copy/pasting.
>>
>> (I’ve seen Python documentation where JS magic allows people to
>toggle
>> prompt display, I find it nice.)
>
>I propose to do a pass on that:
> - apply this rule: no-$ for only input and $ to distinguish between
>inputs and outputs.
> - backtick ` replaced by $(...) as discussed elsewhere
>and then send a "Fix typo" patch.  And maybe add a bullet in the
>Contributing Section.
>
>WDYT?
>
>All the best,
>simon

If there is a way to mark a sentence to wrap it into a class, we could also do some CSS magic with :before. That will allow us to show the prompt while making it non-selectable I think, which is nice visually and for copy-pasting. I'm not a texinfo guru though, so I don't know if it is feasible.

Re: Manual consistency

[Ricardo Wurmus]

Julien Lepiller <julien@lepiller.eu> writes:

> If there is a way to mark a sentence to wrap it into a class, we could
> also do some CSS magic with :before.

Texinfo puts all examples inside div.example pre.example, but the
individual lines are not wrapped in spans, so we cannot style each line
individually.  A :before rule would thus only change the first line,
which is not enough.

-- 
Ricardo

Re: Manual consistency

[Ludovic Courtès]

Hi,

Ricardo Wurmus <rekado@elephly.net> skribis:

> Julien Lepiller <julien@lepiller.eu> writes:
>
>> If there is a way to mark a sentence to wrap it into a class, we could
>> also do some CSS magic with :before.
>
> Texinfo puts all examples inside div.example pre.example, but the
> individual lines are not wrapped in spans, so we cannot style each line
> individually.  A :before rule would thus only change the first line,
> which is not enough.

What about adding some more post-processing in doc/build.scm?  :-)

Ludo’.

Re: Manual consistency

[Ricardo Wurmus]

Ludovic Courtès <ludo@gnu.org> writes:

> Hi,
>
> Ricardo Wurmus <rekado@elephly.net> skribis:
>
>> Julien Lepiller <julien@lepiller.eu> writes:
>>
>>> If there is a way to mark a sentence to wrap it into a class, we could
>>> also do some CSS magic with :before.
>>
>> Texinfo puts all examples inside div.example pre.example, but the
>> individual lines are not wrapped in spans, so we cannot style each line
>> individually.  A :before rule would thus only change the first line,
>> which is not enough.
>
> What about adding some more post-processing in doc/build.scm?  :-)

If we’re okay with wrapping individual lines in @code{…} that won’t be
necessary.  Having each logical line of code within @code results in

  <pre class="example">
    <code>this line</code>
    <code>that line</code>
  </pre>

and that’s something we *can* style with CSS.

-- 
Ricardo

Re: Manual consistency

[Julien Lepiller]

Le 9 juin 2020 13:13:31 GMT-04:00, Ricardo Wurmus <rekado@elephly.net> a écrit :
>
>Ludovic Courtès <ludo@gnu.org> writes:
>
>> Hi,
>>
>> Ricardo Wurmus <rekado@elephly.net> skribis:
>>
>>> Julien Lepiller <julien@lepiller.eu> writes:
>>>
>>>> If there is a way to mark a sentence to wrap it into a class, we
>could
>>>> also do some CSS magic with :before.
>>>
>>> Texinfo puts all examples inside div.example pre.example, but the
>>> individual lines are not wrapped in spans, so we cannot style each
>line
>>> individually.  A :before rule would thus only change the first line,
>>> which is not enough.
>>
>> What about adding some more post-processing in doc/build.scm?  :-)
>
>If we’re okay with wrapping individual lines in @code{…} that won’t be
>necessary.  Having each logical line of code within @code results in
>
>  <pre class="example">
>    <code>this line</code>
>    <code>that line</code>
>  </pre>
>
>and that’s something we *can* style with CSS.

But we can't differentiate root commands and user commands that way.

Re: Manual consistency

[Ricardo Wurmus]

Julien Lepiller <julien@lepiller.eu> writes:

> Le 9 juin 2020 13:13:31 GMT-04:00, Ricardo Wurmus <rekado@elephly.net> a écrit :
>>
>>Ludovic Courtès <ludo@gnu.org> writes:
>>
>>> Hi,
>>>
>>> Ricardo Wurmus <rekado@elephly.net> skribis:
>>>
>>>> Julien Lepiller <julien@lepiller.eu> writes:
>>>>
>>>>> If there is a way to mark a sentence to wrap it into a class, we
>>could
>>>>> also do some CSS magic with :before.
>>>>
>>>> Texinfo puts all examples inside div.example pre.example, but the
>>>> individual lines are not wrapped in spans, so we cannot style each
>>line
>>>> individually.  A :before rule would thus only change the first line,
>>>> which is not enough.
>>>
>>> What about adding some more post-processing in doc/build.scm?  :-)
>>
>>If we’re okay with wrapping individual lines in @code{…} that won’t be
>>necessary.  Having each logical line of code within @code results in
>>
>>  <pre class="example">
>>    <code>this line</code>
>>    <code>that line</code>
>>  </pre>
>>
>>and that’s something we *can* style with CSS.
>
> But we can't differentiate root commands and user commands that way.

… if that’s *really* necessary we can post-process in doc/build.scm, but
I think there’s little value in showing a different prompt.  While I
have seen it elsewhere, it’s not a universal convention to use “#” as a
root prompt and “$” for an unprivileged prompt.

If we want to clearly indicate that this is done by the root user I
suggest including “su -” at the top of the listing.

-- 
Ricardo

Re: Manual consistency

[Ludovic Courtès]

Hello,

Ricardo Wurmus <rekado@elephly.net> skribis:

> Ludovic Courtès <ludo@gnu.org> writes:
>
>> Hi,
>>
>> Ricardo Wurmus <rekado@elephly.net> skribis:
>>
>>> Julien Lepiller <julien@lepiller.eu> writes:
>>>
>>>> If there is a way to mark a sentence to wrap it into a class, we could
>>>> also do some CSS magic with :before.
>>>
>>> Texinfo puts all examples inside div.example pre.example, but the
>>> individual lines are not wrapped in spans, so we cannot style each line
>>> individually.  A :before rule would thus only change the first line,
>>> which is not enough.
>>
>> What about adding some more post-processing in doc/build.scm?  :-)
>
> If we’re okay with wrapping individual lines in @code{…} that won’t be
> necessary.

Adding @code to every single line sounds too intrusive to me.

Ludo’.

Re: Manual consistency

[Dmitry Alexandrov]

[-- Attachment #1: Type: text/plain, Size: 1571 bytes --]

Ricardo Wurmus <rekado@elephly.net> wrote:
> Ludovic Courtès <ludo@gnu.org> writes:
>> Ricardo Wurmus <rekado@elephly.net> skribis:
>>> Julien Lepiller <julien@lepiller.eu> writes:
>>>> If there is a way to mark a sentence to wrap it into a class, we could also do some CSS magic with :before.
>>
>> What about adding some more post-processing in doc/build.scm?  :-)
>
> If we’re okay with wrapping individual lines in @code{…} that won’t be necessary.  Having each logical line of code within @code results in
>
>   <pre class="example">
>     <code>this line</code>
>     <code>that line</code>
>   </pre>
>
> and that’s something we *can* style with CSS.

May I chime in?

Do I get it right: you are suggesting to remove prompts from .texi and put them back in HTML output only — leaving other formats with not prompts?

And that is only to make them unselectable?  I do not quite understand, why this is needed at all (are there multiline examples in the manual, that expected to be blindly copypasted to terminal?), but in any case no hacks like ‘::before’ are required — ‘user-select: none’ is supported by all modern webengines (yet sometimes with prefix):

	  <style>
	    code .PS1 {
	        -webkit-user-select: none;
	        -moz-user-select: none; /* Not required since F***fox 69. */
	        user-select: none;
	    }
	  </style>
	
	  <pre><code><span class="PS1">$ </span>wget …/guix-install.sh
	<span class="PS1">$ </span>su -
	<span class="PS1"># </span>bash ./guix-install.sh
	  </code></pre>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 247 bytes --]

Re: Manual consistency

[Ricardo Wurmus]

Dmitry Alexandrov <dag@gnui.org> writes:

> Ricardo Wurmus <rekado@elephly.net> wrote:
>> Ludovic Courtès <ludo@gnu.org> writes:
>>> Ricardo Wurmus <rekado@elephly.net> skribis:
>>>> Julien Lepiller <julien@lepiller.eu> writes:
>>>>> If there is a way to mark a sentence to wrap it into a class, we could also do some CSS magic with :before.
>>>
>>> What about adding some more post-processing in doc/build.scm?  :-)
>>
>> If we’re okay with wrapping individual lines in @code{…} that won’t be necessary.  Having each logical line of code within @code results in
>>
>>   <pre class="example">
>>     <code>this line</code>
>>     <code>that line</code>
>>   </pre>
>>
>> and that’s something we *can* style with CSS.
>
> May I chime in?
>
> Do I get it right: you are suggesting to remove prompts from .texi and put them back in HTML output only — leaving other formats with not prompts?
>
> And that is only to make them unselectable?  I do not quite understand, why this is needed at all (are there multiline examples in the manual, that expected to be blindly copypasted to terminal?), but in any case no hacks like ‘::before’ are required — ‘user-select: none’ is supported by all modern webengines (yet sometimes with prefix):
>
> 	  <style>
> 	    code .PS1 {
> 	        -webkit-user-select: none;
> 	        -moz-user-select: none; /* Not required since F***fox 69. */
> 	        user-select: none;
> 	    }
> 	  </style>
> 	
> 	  <pre><code><span class="PS1">$ </span>wget …/guix-install.sh
> 	<span class="PS1">$ </span>su -
> 	<span class="PS1"># </span>bash ./guix-install.sh
> 	  </code></pre>

This is good.

The only minor problem is that with Texinfo we cannot insert conditional
tags within the context of an example section, so we would have to
rewrite the HTML via post-processing.

-- 
Ricardo

Re: Manual consistency

[Julien Lepiller]

Le 11 juin 2020 04:33:56 GMT-04:00, Ricardo Wurmus <rekado@elephly.net> a écrit :
>
>Dmitry Alexandrov <dag@gnui.org> writes:
>
>> Ricardo Wurmus <rekado@elephly.net> wrote:
>>> Ludovic Courtès <ludo@gnu.org> writes:
>>>> Ricardo Wurmus <rekado@elephly.net> skribis:
>>>>> Julien Lepiller <julien@lepiller.eu> writes:
>>>>>> If there is a way to mark a sentence to wrap it into a class, we
>could also do some CSS magic with :before.
>>>>
>>>> What about adding some more post-processing in doc/build.scm?  :-)
>>>
>>> If we’re okay with wrapping individual lines in @code{…} that won’t
>be necessary.  Having each logical line of code within @code results in
>>>
>>>   <pre class="example">
>>>     <code>this line</code>
>>>     <code>that line</code>
>>>   </pre>
>>>
>>> and that’s something we *can* style with CSS.
>>
>> May I chime in?
>>
>> Do I get it right: you are suggesting to remove prompts from .texi
>and put them back in HTML output only — leaving other formats with not
>prompts?
>>
>> And that is only to make them unselectable?  I do not quite
>understand, why this is needed at all (are there multiline examples in
>the manual, that expected to be blindly copypasted to terminal?), but
>in any case no hacks like ‘::before’ are required — ‘user-select: none’
>is supported by all modern webengines (yet sometimes with prefix):
>>
>> 	  <style>
>> 	    code .PS1 {
>> 	        -webkit-user-select: none;
>> 	        -moz-user-select: none; /* Not required since F***fox 69. */
>> 	        user-select: none;
>> 	    }
>> 	  </style>
>> 	
>> 	  <pre><code><span class="PS1">$ </span>wget …/guix-install.sh
>> 	<span class="PS1">$ </span>su -
>> 	<span class="PS1"># </span>bash ./guix-install.sh
>> 	  </code></pre>
>
>This is good.
>
>The only minor problem is that with Texinfo we cannot insert
>conditional
>tags within the context of an example section, so we would have to
>rewrite the HTML via post-processing.

Maybe that's what we want to do? If a line in <pre> satrts with "$ " or "# " wrap with a span. That way, we can make them unselectable in html, and they still appear in the info manual. We also keep the distinction between $ and #.

Re: Manual consistency

[Dmitry Alexandrov]

[-- Attachment #1: Type: text/plain, Size: 835 bytes --]

Ricardo Wurmus <rekado@elephly.net> wrote:
> Dmitry Alexandrov <dag@gnui.org> writes:
>>
>> 	  <style>
>> 	    code .PS1 {
>> 	        -webkit-user-select: none;
>> 	        -moz-user-select: none; /* Not required since F***fox 69. */
>> 	        user-select: none;
>> 	    }
>> 	  </style>
>
> The only minor problem is that with Texinfo we cannot insert conditional tags within the context of an example section

Dunno, I can:

	\input texinfo
	@setfilename non-selectable-command-prompts-mwe.info
	@documentencoding UTF-8
	@settitle Non-selectable command prompts
	
	@macro PS1 {prompt}
	@inlineraw{html,<span class="PS1">}\prompt\@inlineraw{html,</span>}
	@end macro
	
	@node Example
	
	@example
	@PS1{$ }wget …/guix-install.sh
	@PS1{$ }su -
	@PS1{# }bash ./guix-install.sh
	@end example
	
	@bye

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 247 bytes --]

Re: Manual consistency

[Ricardo Wurmus]

Dmitry Alexandrov <dag@gnui.org> writes:

> Ricardo Wurmus <rekado@elephly.net> wrote:
>> Dmitry Alexandrov <dag@gnui.org> writes:
>>>
>>> 	  <style>
>>> 	    code .PS1 {
>>> 	        -webkit-user-select: none;
>>> 	        -moz-user-select: none; /* Not required since F***fox 69. */
>>> 	        user-select: none;
>>> 	    }
>>> 	  </style>
>>
>> The only minor problem is that with Texinfo we cannot insert conditional tags within the context of an example section
>
> Dunno, I can:
>
> 	\input texinfo
> 	@setfilename non-selectable-command-prompts-mwe.info
> 	@documentencoding UTF-8
> 	@settitle Non-selectable command prompts
> 	
> 	@macro PS1 {prompt}
> 	@inlineraw{html,<span class="PS1">}\prompt\@inlineraw{html,</span>}
> 	@end macro
> 	
> 	@node Example
> 	
> 	@example
> 	@PS1{$ }wget …/guix-install.sh
> 	@PS1{$ }su -
> 	@PS1{# }bash ./guix-install.sh
> 	@end example
> 	
> 	@bye

Oh, neat!  Let’s try this.

-- 
Ricardo

Re: Manual consistency

[Dmitry Alexandrov]

[-- Attachment #1: Type: text/plain, Size: 894 bytes --]

Ricardo Wurmus <rekado@elephly.net> wrote:
> Dmitry Alexandrov <dag@gnui.org> writes:
>> 	@macro PS1 {prompt}
>> 	@inlineraw{html,<span class="PS1">}\prompt\@inlineraw{html,</span>}
>> 	@end macro
>
> Oh, neat!  Let’s try this.

Oops!  (info "(texinfo) Defining Macros") recommends against using digits in macro names:

| For a macro to work consistently with TeX, MACRONAME must consist entirely of letters: no digits, hyphens, underscores, or other special characters.  So, we recommend using only letters.  However, 'makeinfo' will accept anything consisting of alphanumerics, and (except as the first character) '-'.

and rightfully so:

	make non-selectable-command-prompts-mwe.pdf
	‹…›
	./non-selectable-command-prompts-mwe.texi:13: Undefined control sequence.
	l.13 @PS
	        1{$ }wget …/guix-install.sh
	?

So s/PS1/prompt/g or whatever suits better.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 247 bytes --]

Re: Manual consistency

[Ricardo Wurmus]

Julien Lepiller <julien@lepiller.eu> writes:

> If there is a way to mark a sentence to wrap it into a class, we could
> also do some CSS magic with :before. That will allow us to show the
> prompt while making it non-selectable I think, which is nice visually
> and for copy-pasting. I'm not a texinfo guru though, so I don't know
> if it is feasible.

We can wrap each line in an @example with @code and then style each of
these lines.

So we would do something like this:

--8<---------------cut here---------------start------------->8---
@example
@code{cd /tmp}
@code{tar --warning=no-timestamp -xf \
  /path/to/guix-binary-@value{VERSION}.x86_64-linux.tar.xz}
@code{mv var/guix /var/ && mv gnu /}
@end example
--8<---------------cut here---------------end--------------->8---

and then add this CSS rule:

--8<---------------cut here---------------start------------->8---
div.example pre.example code::before {
  content: "$ ";
}
--8<---------------cut here---------------end--------------->8---

In the manual sometimes the prompt is # (for root) and sometimes it is $
(when it’s any other user).  We cannot distinguish these cases unless we
abuse the Texinfo format by wrapping examples to allow for a more
explicit rule to match. 

-- 
Ricardo

Re: Manual consistency

[George Clemmer]

zimoun <zimon.toutoune@gmail.com> writes:

> (from: http://issues.guix.gnu.org/issue/41253#10)
>
> On Fri, 5 Jun 2020 at 18:36, Ludovic Courtès <ludo@gnu.org> wrote:
>
>> > There are many examples in guix.texi with $, and also many without. Plus
>> > some with # as the command line prompt.

>> I’ve come to the conclusion that snippets that contain only input should
>> be written without a prompt, for easier copy/pasting.

> I propose to do a pass on that:
>  - apply this rule: no-$ for only input and $ to distinguish between
> inputs and outputs.

+1.

For examples w/ outputs, how about also removing the $ and commenting
the outputs with '# ', or '# > '?

HTH - George