styles for root and normal user shell command

[Federico Bruni]

Hi,

the easiest way to enter shell commands is probably not using any $ and
# sign in front of the command and using sudo for commands to be run as
root.

But it would be nice to handle it differently.

I'd like to be able to define two styles for shell commands.
I don't want to use "sudo" in the root commands.
I'd like to enter only the real command in the literal block, with no
leading $ or # (because it's not handy for copy&paste).

$ and # signs should be added by a style, that I may specify as a option
of the literal block.

Something like this:

Install the dependencies::
:user: root
aptitude install bla bla bla

Run the program::
:user: user
python program.py


What do you recommend to do?
Also, how can I style the shell commands differently from other literal
blocks?

Thanks,
Federico

[Guenter Milde]

On 2012-06-12, Federico Bruni wrote:
> Hi,

> the easiest way to enter shell commands is probably not using any $ and
> # sign in front of the command and using sudo for commands to be run as
> root.

> But it would be nice to handle it differently.

> I'd like to be able to define two styles for shell commands.
> I don't want to use "sudo" in the root commands.
> I'd like to enter only the real command in the literal block, with no
> leading $ or # (because it's not handy for copy&paste).

> $ and # signs should be added by a style, that I may specify as a option
> of the literal block.

> Something like this:

> Install the dependencies::
> :user: root
> aptitude install bla bla bla

> Run the program::
> :user: user
> python program.py


> What do you recommend to do?

a) use the "sh" lexer, give a class value to the input and use a custom
style (CSS rule with class selector with HTML, tricky or maybe
impossible with LaTeX/PDF)::

.. code:: sh
:class: user

python program.py

.. code:: sh
:class: root

python setup.py install

(The "code" directive is new in reStructuredText (docutils 0.9
(2012-05-02). Use the Sphinx extension "sourcecode" with earlier
Docutils versions.)

b) Create and use Pygments lexers, e.g. "shell-user" vs. "shell-root" (or
just use the existing "sh" lexer). See
http://pygments.org/docs/lexers/#lexers-for-various-shells and
http://pygments.org/docs/lexerdevelopment/

> Also, how can I style the shell commands differently from other literal
> blocks?

Either use the "code" directive, ::

.. code:: sh

ls -l

or set the "default literal block style":

The highlighting language can be changed using the highlight directive,
used as follows::

.. highlight:: c

This language is used until the next highlight directive is
encountered.

-- http://sphinx.pocoo.org/markup/code.html


Günter

[Helix Roveda]

Hi Federico!

> ...

> Something like this:
>
> Install the dependencies::
>   :user: root
>   aptitude install bla bla bla
>
> Run the program::
>   :user: user
>   python program.py
>
>
> What do you recommend to do?

I have no suggestion for that.

> Also, how can I style the shell commands differently from other literal
> blocks?

You can use the

.. code-block:: bash
:emphasize-lines: 2

$ ls -al
# kill 5678

But Pygments is needed for syntax highlighting.
Perhaps, the :emphasize-lines: can be used to point out those lines
which must be executed as root?
Well, that's obviously only a work-around for what you want.

Many regards,
Helix

[Federico Bruni]

Il 12/06/2012 11:31, Guenter Milde ha scritto:
> a) use the "sh" lexer, give a class value to the input and use a custom
> style (CSS rule with class selector with HTML, tricky or maybe
> impossible with LaTeX/PDF)::
>
> .. code:: sh
> :class: user
>
> python program.py
>
> .. code:: sh
> :class: root
>
> python setup.py install
>
> (The "code" directive is new in reStructuredText (docutils 0.9
> (2012-05-02). Use the Sphinx extension "sourcecode" with earlier
> Docutils versions.)

Did you really mean "sourcecode"?
I can't find it in the builtin directives neither in the community
extensions:
https://bitbucket.org/birkenfeld/sphinx-contrib/src

Currently I have docutils 0.8 on my debian system.
I've tried installing latest svn version but code is not recognized:

ERROR: Unknown directive type "code".

.. code:: sh

aptitude install package


The new docutils installation is in /usr/local, so it should have
priority over debian package in /usr:

# ls -l /usr/local/bin/rst*
-rwxr-xr-x 1 root staff 546 giu 13 00:38 /usr/local/bin/rst2html.py
-rwxr-xr-x 1 root staff 744 giu 13 00:38 /usr/local/bin/rst2latex.py
-rwxr-xr-x 1 root staff 600 giu 13 00:38 /usr/local/bin/rst2man.py
-rwxr-xr-x 1 root staff 188 mar 19 2011 /usr/local/bin/rst2newlatex.py
-rwxr-xr-x 1 root staff 1639 giu 13 00:38
/usr/local/bin/rst2odt_prepstyles.py
-rwxr-xr-x 1 root staff 716 giu 13 00:38 /usr/local/bin/rst2odt.py
-rwxr-xr-x 1 root staff 548 giu 13 00:38 /usr/local/bin/rst2pseudoxml.py
-rwxr-xr-x 1 root staff 591 giu 13 00:38 /usr/local/bin/rst2s5.py
-rwxr-xr-x 1 root staff 739 giu 13 00:38 /usr/local/bin/rst2xetex.py
-rwxr-xr-x 1 root staff 555 giu 13 00:38 /usr/local/bin/rst2xml.py
-rwxr-xr-x 1 root staff 619 giu 13 00:38 /usr/local/bin/rstpep2html.py

[Federico Bruni]

Il 13/06/2012 00:48, Federico Bruni ha scritto:
> Currently I have docutils 0.8 on my debian system.
> I've tried installing latest svn version but code is not recognized:

Nevermind, it didn't work because I followed the README in docutils
source code (which recommended using python3), so Sphinx didn't look in
/usr/local/lib/python3.2

Now I've installed docutils in python2.7 and Sphinx recognize code
directive.

I'll look through custom style tomorrow night.
Thanks,
Federico

[Federico Bruni]

Il 12/06/2012 11:31, Guenter Milde ha scritto:

> a) use the "sh" lexer, give a class value to the input and use a custom
> style (CSS rule with class selector with HTML

What's the best way to add a custom style?
I can imagine it's been asked before, but I couldn't find anything
useful in the documentation and in the archives.

Best hint was in conf.py, about the _static directory.
So I created _static/custom.css and inserted these lines:

@import url("default.css");

div.code.sh.root {
background: #4D8DFE;
}

But it doesn't work. What's wrong?

I must say that I don't have a full understanding of the classes here.
I can see on firebug that:

.. code: sh
:class: root

assigns the class "code sh root highlight-python" (or highlight-none if
highlighting is disabled in conf.py).

Thanks in advance,
Federico

[Takayuki Shimizukawa]

Hi Federico,

2012/6/13 Federico Bruni <fede...@gmail.com>:

> What's the best way to add a custom style?
> I can imagine it's been asked before, but I couldn't find anything useful in
> the documentation and in the archives.
>
> Best hint was in conf.py, about the _static directory.
> So I created _static/custom.css and inserted these lines:
>
> @import url("default.css");
>
> div.code.sh.root {
>    background: #4D8DFE;
> }
>
> But it doesn't work. What's wrong?

Probably, custom.css is not refer from a HTML page.
It is necessary to write the following codes into "conf.py".:

def setup(app):
app.add_stylesheet('custom.css')

# and costom.css don't need "@import url("default.css");".
# see also: http://sphinx.pocoo.org/ext/appapi.html#sphinx.application.Sphinx.add_stylesheet

Best regards.
--
Takayuki SHIMIZUKAWA
Sphinx-users.jp

[Guenter Milde]

On 2012-06-12, Federico Bruni wrote:

> Il 13/06/2012 00:48, Federico Bruni ha scritto:
>> Currently I have docutils 0.8 on my debian system.
>> I've tried installing latest svn version but code is not recognized:

> Nevermind, it didn't work because I followed the README in docutils
> source code (which recommended using python3), so Sphinx didn't look in
> /usr/local/lib/python3.2

This must be a misunderstanding. Docutils works with Python 2.3 and
newer but is less tested under Python 3. For Sphinx, you need an
installation under 2.x.

In order to use Docutils under Python 3, it needs to be set up under
Python 3, because only then the sources are converted to 3-compatible
versions.

If you want to use it under both, Python 2.x and Python 3.x, run e.g.

.. code:: sh

cd <the unpacked archive' root>
cd test
python alltests.py
cd ..
python3 setup.py build
cd test3
python3 alltests.py
cd ..

and if no critical errors turn up:

.. code:: sh
:class: root

cd <the unpacked archive' root>
python3 setup.py install
python setup.py install

(The last setup command should use the default Python version, as
distutils puts the command it was called with in the shebang line of the
executables.)

The latter code block translates here to::

<p>and if no critical errors turn up:</p>
<pre class="code sh root literal-block">
<span class="nb">cd</span> &lt;the unpacked archive<span class="err">'</span> root&gt;
python3 setup.py install
python setup.py install
</pre>

which should match a CSS rule like::

pre.sh.root {background: red;}

However, prefixing some command line prompt via CSS does not work, as the
lines are not wrapped in a tag.

Günter

[Guenter Milde]

On 2012-06-12, Federico Bruni wrote:

> Il 12/06/2012 11:31, Guenter Milde ha scritto:

>> (The "code" directive is new in reStructuredText (docutils 0.9
>> (2012-05-02). Use the Sphinx extension "sourcecode" with earlier
>> Docutils versions.)


> Did you really mean "sourcecode"?

No. In Sphinx it is "source-block". Sorry for mixing it up.

Günter

[Federico Bruni]

> G�nter
>

Sorry, you were right: I didn't specify an argument.
In Sphinx it's called code-block and sourcecode is its alias:

http://sphinx.pocoo.org/markup/code.html

I think this link is quite hidden in the documentation.
Well, it's in the index, but the first link that one will check is
probably this one:

http://sphinx.pocoo.org/rest.html#source-code

Why don't you add there a link to markup/code.html?

Thanks,
Federico

[Federico Bruni]

Il 13/06/2012 09:23, Guenter Milde ha scritto:
> .. code:: sh
> :class: root
>
> cd<the unpacked archive' root>
> python3 setup.py install
> python setup.py install
>
> (The last setup command should use the default Python version, as
> distutils puts the command it was called with in the shebang line of the
> executables.)
>
> The latter code block translates here to::
>
> <p>and if no critical errors turn up:</p>
> <pre class="code sh root literal-block">
> <span class="nb">cd</span> &lt;the unpacked archive<span class="err">'</span> root&gt;
> python3 setup.py install
> python setup.py install
> </pre>
>
> which should match a CSS rule like::
>
> pre.sh.root {background: red;}
>

mmh, for me it works this way:

.sh.root pre {background: red;}

> However, prefixing some command line prompt via CSS does not work, as the
> lines are not wrapped in a tag.

I see: I think I'll end up using a general style for shell prompt and
use 'sudo' to show the commands which need root privileges.
Thinking twice, it's better, because quite often a single code block
might include root and normal user commands.

So I guess my CSS style will be something like this:

.code.sh pre {
background-color: #000;
color: #EDEDED;
font-family: Courier;
}

Thanks all for your help!

Federico

[Federico Bruni]

Il 13/06/2012 21:18, Federico Bruni ha scritto:
> I see: I think I'll end up using a general style for shell prompt and
> use 'sudo' to show the commands which need root privileges.
> Thinking twice, it's better, because quite often a single code block
> might include root and normal user commands.
>
> So I guess my CSS style will be something like this:
>
> .code.sh pre {
> background-color: #000;
> color: #EDEDED;
> font-family: Courier;
> }

Thinking twice again.. using for any bash command:

.. code:: sh

is not handy at all.
I'd rather use the literal block and specify the highlight I want in the
conf.py or in the beginning of the document:

.. highlight:: sh

Which means the CSS class to override will be:

.highlight-sh pre {background: #000}

[Guenter Milde]

Indeed. Looking at the generated HTML, if find two levels of divs::

<div class="highlight-sh"><div class="highlight"><pre>
...
</pre></div>
</div>

instead of the simple ``<pre class="highlight sh">``.
May be worth a bug report.

Günter

[Guenter Milde]

On 2012-06-13, Federico Bruni wrote:

> Il 13/06/2012 09:25, Guenter Milde ha scritto:
>> On 2012-06-12, Federico Bruni wrote:
>>> Il 12/06/2012 11:31, Guenter Milde ha scritto:

>>>> (The "code" directive is new in reStructuredText (docutils 0.9
>>>> (2012-05-02). Use the Sphinx extension "sourcecode" with earlier
>>>> Docutils versions.)


>>> Did you really mean "sourcecode"?

>> No. In Sphinx it is "source-block". Sorry for mixing it up.

>> Günter

> Sorry, you were right: I didn't specify an argument.
> In Sphinx it's called code-block and sourcecode is its alias:

> http://sphinx.pocoo.org/markup/code.html

> I think this link is quite hidden in the documentation.
> Well, it's in the index, but the first link that one will check is
> probably this one:

> http://sphinx.pocoo.org/rest.html#source-code

Actually, the section title is incorrect: the `literal block`_ in
reStructuredText_ is not a "Source Code" element but a generic
block-level element (like the <pre> HTML element).

The literal_block element contains a block of text where line breaks
and whitespace are significant and must be preserved. literal_block
elements are commonly used for program listings and
interactive computer sessions.

-- http://docutils.sourceforge.net/docs/ref/doctree.html#literal-block

.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _literal block: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#literal-blocks

Highlight of literal blocks (and the implied notation that literal blocks
are source code by default) is a Sphinx extension. Hence, a link to
markup/code.html is in place.

> Why don't you add there a link to markup/code.html?

Because I am not a Sphinx developer.

Günter