Mailing List Archive: Gentoo: Doc

Why do we run all commands as root in docs?

Index | Next | Previous | View Threaded

rane at gentoo

Sep 6, 2005, 5:28 AM

Post #1 of 6 (629 views)
Permalink

Why do we run all commands as root in docs?

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Greetings,

I'm not filing a bug but writing here, because i think that this case
needs policy change and some discussion in the team before that as it
will lead to really lots of fixing in our docs.

Now situation looks really strange. We encourage users not to use root
account in security docs, but all over our place, in every code
listing, we have root prompt ("#") which suggests users to use that
account to perform all the actions.

My idea is that we should use "$" - user prompt - whereever command can
be or should be run as normal user.

Example?

http://www.gentoo.org/proj/en/gdp/doc/doc-tipsntricks.xml:

# wget http://www.gentoo.org/dyn/doc-snapshots/docs-latest-en.tar.bz2

Why we should download it as root? Why not just:

$ wget http://www.gentoo.org/dyn/doc-snapshots/docs-latest-en.tar.bz2?

For me, it could reduce bad behaviour of doing simple commands as root,
which is not needed and should be avoided as much as possible.

Of course i know that when all our docs contain such prompts, fixing it
would cost lots of resources and can accept if you refuse due to that.

I also know that users don't have to be informed what those strange
prompt signs (#, $) mean, but that can be easily solved with small note
in index.xml files.

I'm waiting for your opinions.

with kind regards,

£ukasz Damentko

(who bought many extra fingers already)
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (GNU/Linux)

iD8DBQFDHYuK8rb4OBjOeLMRAo/DAJ9++5fJLIGR02IKH0aH0f91RzEG3QCfUrD0
+m1wLfxNN11FYleh9Rd+998=
=D2Pn
-----END PGP SIGNATURE-----
--
gentoo-doc [at] gentoo mailing list

fox2mike at gentoo

Sep 6, 2005, 7:09 AM

Post #2 of 6 (607 views)
Permalink

Re: Why do we run all commands as root in docs? [In reply to]

Åukasz Damentko wrote:

> My idea is that we should use "$" - user prompt - whereever command can
> be or should be run as normal user.

As much as I hate to do this, I think that this does make sense...

I feel the following change(s) [any one] needs to be implemented :

a) Use a common prompt for all. Either # or $ (as YosWink mentioned on
IRC) OR

b) Use $ for user commands and # for root commands.

Initially, it'll be quite a bit of changes/commits...but I think this is
worth it in the long run...

> (who bought many extra fingers already)

No Toes? :D Buy those too....you never know...

--
Shyam Mani | <fox2mike [at] gentoo>
docs-team | http://gdp.gentoo.org
GPG Key | 0xFDD0E345

Attachments:

signature.asc (0.18 KB)

neysx at gentoo

Sep 6, 2005, 7:16 AM

Post #3 of 6 (602 views)
Permalink

Re: Why do we run all commands as root in docs? [In reply to]

Åukasz Damentko wrote:
> Now situation looks really strange. We encourage users not to use root
> account in security docs, but all over our place, in every code
> listing, we have root prompt ("#") which suggests users to use that
> account to perform all the actions.

Most of our docs are about installing and configuring stuff so it's not really
a surprise most prompts are #

> My idea is that we should use "$" - user prompt - whereever command can
> be or should be run as normal user.

Right.

> Example?
> http://www.gentoo.org/proj/en/gdp/doc/doc-tipsntricks.xml:

Fixed.

If you find others, please file a bug and start listing them.

Cheers,
--
/ Xavier Neys
\_ Gentoo Documentation Project
/ French & Internationalisation Lead
\ http://www.gentoo.org/doc/en
/\

--
gentoo-doc [at] gentoo mailing list

swift at gentoo

Sep 6, 2005, 10:54 AM

Post #4 of 6 (603 views)
Permalink

Re: Why do we run all commands as root in docs? [In reply to]

On Tue, Sep 06, 2005 at 02:28:58PM +0200, Åukasz Damentko wrote:
> Now situation looks really strange. We encourage users not to use root
> account in security docs, but all over our place, in every code
> listing, we have root prompt ("#") which suggests users to use that
> account to perform all the actions.
>
> My idea is that we should use "$" - user prompt - whereever command can
> be or should be run as normal user.

Like Xavier said, most documents have ~# or # because they talk about
configuration settings. However, when possible, we should indeed use ~$ or $
instead.

Wkr,
Sven Vermeulen

--
Gentoo Foundation Trustee | http://foundation.gentoo.org
Gentoo Documentation Project Lead | http://www.gentoo.org/proj/en/gdp
Gentoo Council Member

The Gentoo Project <<< http://www.gentoo.org >>>

smithj at gentoo

Sep 9, 2005, 8:05 AM

Post #5 of 6 (602 views)
Permalink

Re: Why do we run all commands as root in docs? [In reply to]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Sven Vermeulen wrote:
> Like Xavier said, most documents have ~# or # because they talk about
> configuration settings. However, when possible, we should indeed use ~$ or $
> instead.

Some documents (like the fluxbox guide) already do this, so it would just be a
matter of fixing the b0rken ones...

I need to do some documentation stuff, so I'll scour the docs this weekend if
thats ok with all.

- --

smithj

Gentoo Developer
[ desktop stuff && network monitoring && documentation ]

Every email I send is digitally signed with OpenPGP key ID 33E2528C, available
from pgp.mit.edu

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFDIaSll5AvwDPiUowRAieeAJ9Axr7kGWnUOlj8iLWH7QxC3/aPzQCbBPXD
epNGsar0cpK8JmP7HaOyQdQ=
=lyFa
-----END PGP SIGNATURE-----
--
gentoo-doc [at] gentoo mailing list

rane at gentoo

Sep 9, 2005, 9:29 AM

Post #6 of 6 (605 views)
Permalink

Re: Why do we run all commands as root in docs? [In reply to]

On Fri, 09 Sep 2005 11:05:09 -0400
Jonathan Smith <smithj [at] gentoo> wrote:

> Some documents (like the fluxbox guide) already do this, so it would just be a
> matter of fixing the b0rken ones...
>
> I need to do some documentation stuff, so I'll scour the docs this weekend if
> thats ok with all.

Handbook and many other docs are ok too. I think it isn't that common
mistake I assumed first. I corrected few docs already, and will review
more of them soon, see http://bugs.gentoo.org/show_bug.cgi?id=105024
for more info.

with regards,

Åukasz Damentko

--
polish lead translator
--
gentoo-doc [at] gentoo mailing list

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads