Re: Manual consistency
Ricardo Wurmus wrote:
> Dmitry Alexandrov writes:
>> @macro PS1 {prompt}
>> @inlineraw{html,}\prompt\@inlineraw{html,}
>> @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.
signature.asc
Description: PGP signature
Re: Manual consistency
Dmitry Alexandrov writes:
> Ricardo Wurmus wrote:
>> Dmitry Alexandrov writes:
>>>
>>>
>>> code .PS1 {
>>> -webkit-user-select: none;
>>> -moz-user-select: none; /* Not required since F***fox 69. */
>>> user-select: none;
>>> }
>>>
>>
>> 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,}\prompt\@inlineraw{html,}
> @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
Ricardo Wurmus wrote:
> Dmitry Alexandrov writes:
>>
>>
>> code .PS1 {
>> -webkit-user-select: none;
>> -moz-user-select: none; /* Not required since F***fox 69. */
>> user-select: none;
>> }
>>
>
> 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,}\prompt\@inlineraw{html,}
@end macro
@node Example
@example
@PS1{$ }wget …/guix-install.sh
@PS1{$ }su -
@PS1{# }bash ./guix-install.sh
@end example
@bye
signature.asc
Description: PGP signature
Re: Manual consistency
Le 11 juin 2020 04:33:56 GMT-04:00, Ricardo Wurmus a écrit
:
>
>Dmitry Alexandrov writes:
>
>> Ricardo Wurmus wrote:
>>> Ludovic Courtès writes:
Ricardo Wurmus skribis:
> Julien Lepiller 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
>>>
>>>
>>> this line
>>> that line
>>>
>>>
>>> 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):
>>
>>
>> code .PS1 {
>> -webkit-user-select: none;
>> -moz-user-select: none; /* Not required since F***fox 69. */
>> user-select: none;
>> }
>>
>>
>>$ wget …/guix-install.sh
>> $ su -
>> # bash ./guix-install.sh
>>
>
>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 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 writes:
> Ricardo Wurmus wrote:
>> Ludovic Courtès writes:
>>> Ricardo Wurmus skribis:
Julien Lepiller 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
>>
>>
>> this line
>> that line
>>
>>
>> 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):
>
>
> code .PS1 {
> -webkit-user-select: none;
> -moz-user-select: none; /* Not required since F***fox 69. */
> user-select: none;
> }
>
>
> $ wget …/guix-install.sh
> $ su -
> # bash ./guix-install.sh
>
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
Ricardo Wurmus wrote:
> Ludovic Courtès writes:
>> Ricardo Wurmus skribis:
>>> Julien Lepiller 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
>
>
> this line
> that line
>
>
> 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):
code .PS1 {
-webkit-user-select: none;
-moz-user-select: none; /* Not required since F***fox 69. */
user-select: none;
}
$ wget …/guix-install.sh
$ su -
# bash ./guix-install.sh
signature.asc
Description: PGP signature
Re: Manual consistency
Hello,
Ricardo Wurmus skribis:
> Ludovic Courtès writes:
>
>> Hi,
>>
>> Ricardo Wurmus skribis:
>>
>>> Julien Lepiller 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
Julien Lepiller writes:
> Le 9 juin 2020 13:13:31 GMT-04:00, Ricardo Wurmus a
> écrit :
>>
>>Ludovic Courtès writes:
>>
>>> Hi,
>>>
>>> Ricardo Wurmus skribis:
>>>
Julien Lepiller 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
>>
>>
>>this line
>>that line
>>
>>
>>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
zimoun writes: > (from: http://issues.guix.gnu.org/issue/41253#10) > > On Fri, 5 Jun 2020 at 18:36, Ludovic Courtès 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
Re: Manual consistency
Le 9 juin 2020 13:13:31 GMT-04:00, Ricardo Wurmus a écrit :
>
>Ludovic Courtès writes:
>
>> Hi,
>>
>> Ricardo Wurmus skribis:
>>
>>> Julien Lepiller 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
>
>
>this line
>that line
>
>
>and that’s something we *can* style with CSS.
But we can't differentiate root commands and user commands that way.
Re: Manual consistency
Ludovic Courtès writes:
> Hi,
>
> Ricardo Wurmus skribis:
>
>> Julien Lepiller 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
this line
that line
and that’s something we *can* style with CSS.
--
Ricardo
Re: Manual consistency
Hi, Ricardo Wurmus skribis: > Julien Lepiller 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
Julien Lepiller 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
Julien Lepiller 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
Le 5 juin 2020 13:34:57 GMT-04:00, zimoun a écrit : >Hi Ludo, > >(from: http://issues.guix.gnu.org/issue/41253#10) > >On Fri, 5 Jun 2020 at 18:36, Ludovic Courtès 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.
