Handbook issue - copying commands

T

taiwan740

In the handbook, there are commands on the pages, for example, - https://docs.freebsd.org/en/books/handbook/cutting-edge/

Chapter 26. Updating and Upgrading FreeBSD​

This has the black sections which note commands to run.

# shutdown -r now

When clicking the "Copy to clipboard" button on the top right of the element, it also includes the prefixed #, which then gives a "Command not found" or doesn't actually run the command.

Running # shutdown -r now doesn't do anything on my machine.

This could lead to confusion in those who are less familiar with shell commands.

Maybe by design, or is known? But thought it worth noting.
 
apart from the fact that those boxes also include the responses or hold nothing but output from another command, and hence are useless if copied as whole, one should *NEVER* copy & paste commands without *understanding* what they do.

IMHO the only correct way is to remove that 'copy' feature from the handbook. It isn't useful anyways due to the way those code-boxes are used (i.e. not for 'code').
 
sko said:
one should *NEVER* copy & paste commands without *understanding* what they do.
Click to expand...
Sort of agree in principle and on paper, but firstly, this is the handbook, so it should be explained what step is doing what, and it does. Above that comment, it says "The machine should now be restarted with the updated kernel:" and then provides that command.

If you're doing something long-winded like upgrading an OS instance, it is a right pain to have to either copy the command and then scroll the cursor back to the start to remove the # or %, or have to type the thing out in its entirety. One's machine is likely to end up in the proverbial hotel swimming pool if we have to keep on like that.

Having the explanation of the # and % thing in the preface is all well and good, but when you're several chapters deep, your brain is already fried trying to get your new OS to work.

Secondly, in reality or perhaps philosophically, nobody understands half the commands and switches these systems use. It's esoteric as it is, as is spoken languages like English and Japanese, the only way humans learn them is by saying words we don't understand.
 
In the interest of not being "that guy" who points out stuff and doesn't try to help... :)

It looks like copy-clipboard.min.js is looking for elements encapsulated by the "rouge" class. This JS could be modifed to parse the value and trim off % or #, and then a left trim to remove any space after that, in order to copy just the command required. (Assuming the commands are written consistently across the handbook - maybe another class could be made for commands as opposed to code/text blocks, if the rouge tag isn't "clean" and single-purpose?)
 
taiwan740 said:
In the interest of not being "that guy" who points out stuff and doesn't try to help... :)

It looks like copy-clipboard.min.js is looking for elements encapsulated by the "rouge" class. This JS could be modifed to parse the value and trim off % or #, and then a left trim to remove any space after that, in order to copy just the command required. (Assuming the commands are written consistently across the handbook - maybe another class could be made for commands as opposed to code/text blocks, if the rouge tag isn't "clean" and single-purpose?)
Click to expand...

Yes, if it can be mangled to copy only pre-defined sections (i.e. the actual command), the copy feature would actually become useful.

I bet the documentation project team (freebsd-doc@freebsd.org) would be grateful for any submissions ;)
You can also reach them via https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Documentation
 
taiwan740 said:
Having the explanation of the # and % thing in the preface is all well and good, but when you're several chapters deep, your brain is already fried trying to get your new OS to work.

Secondly, in reality or perhaps philosophically, nobody understands half the commands and switches these systems use. It's esoteric as it is, as is spoken languages like English and Japanese, the only way humans learn them is by saying words we don't understand.
Click to expand...
Read once, learned forever.

Those little unix-like things are learned by coming into contact with the system, like understanding that you use repositories instead of .exe downloads or need su/sudo for the administrator account.
If you live a few weeks on the console: lynx, mutt, find, cat, grep, ls, more, man!... the general commands become trivial, you'll even remember the common parameters (-e, -r...) and the keys of the man pages/lynx/editor... (h:help, space: pager, q:quit, /:search, n:next, p: prev).
 
You must log in or register to reply here.
Back
Top