Skip to content
Snippets Groups Projects
New look: Off

Clarify in Style Guide: shell commands -- prefix with dollar sign or not?

    • Closed Issue created by homotechsual @homotechsual

    Created by: seancolsen

    When I write documentation that instructs the user to execute a shell command, how should I write it?

    With the dollar sign

    $ civibuild create dmaster --url http://dmaster

    Without the dollar sign

    civibuild create dmaster --url http://dmaster

    I think it'd be nice if we were consistent on this matter, so I think it'd be a good candidate for putting in the style guide.

    I don't have an opinion either way. Do you?

    Designs

      Child items ...

      2. Activity

      • homotechsual
        homotechsual @homotechsual ·
        Author Owner

        Created by: MegaphoneJon

        IMO, the main effect this has is to inhibit copy/pasting multiple lines of shell code.

        While I can see the argument that it would be a feature, not a bug, to do so, I'm not on board. While I don't run shell code I don't understand - anymore - there's no doubt I would have never learned all I have unless I was able to get somewhere through the use of copy/paste. So I would support leaving the dollar sign out.

      • homotechsual
        homotechsual @homotechsual ·
        Author Owner

        Created by: totten

        Agree with Jon that it's easier to copy-paste if you omit the dollar sign.

        However, the commands often aren't written in isolation, eg

        • If there are multiple commands, then we might mingle in some comments about flow/motivation/purpose.
        • If the output is significant to the discussion, then we might show it as part of blob.

        If you looked at docs I wrote, you'd probably see inconsistent usage of $. But there maybe a hidden rule which I'm following:

        • If there's output interleaved, then include the $. (This removes ambiguity about input-vs-output.)
        • If there's no output interleaved, then omit the $. (This is easier to copy paste.) (Exception: if you're in a page where many other blurbs us $, then you might adjust to match them.)

        For some examples, see my Angular PR:

        https://github.com/totten/civicrm-dev-docs/blob/master-angular/docs/framework/angular/quickstart.md#open-the-page

        The section "Open the page" is actually pretty carefully considered for readers of multiple perspectives:

        • Providing the visual output gives enough clues that you should be able to figure the URL by yourself. You don't need cv at all. (And, at this point in this page, there's no guarantee that you have it installed!)
        • Providing the command gives a fallback -- a way you can figure out more complicated scenarios.
        • If we just showed one example URL for Drupal, it would be confusing to Joomla/WordPress folks -- they'd incorrectly guess the URL.
      • homotechsual
        homotechsual @homotechsual ·
        Author Owner

        Created by: totten

        Another variation that shows up: sometimes the PWD is indicated.

        • This is useful since PWD can be significant, and it's a common mistake for novices to mix up their PWD. It pains me to see support requests (there were several in the past) because someone was in the wrong PWD. Showing the PWD helps you error-correct.
        • But it can also be redundant/distracting sometimes (eg if you're not changing the path; or if it's obvious or redundant).
      • homotechsual
        homotechsual @homotechsual ·
        Author Owner

        Created by: totten

        More thoughts:

        • The basic defense of the "inconsistent" approach: context matters, and sometimes you need to communicate different things, and it's technically KISS.
        • In an ideal world, the markdown processor would render input/output/comment lines differently. (eg display $ as a background image; or colorcode lines).

        Trying to pursue the latter a bit... this snippet seems interesting.

        $ civix generate:module org.example.aboutme
Initalize module org.example.aboutme
Write org.example.aboutme/info.xml
Write org.example.aboutme/aboutme.php
Write org.example.aboutme/aboutme.civix.php
Write org.example.aboutme/LICENSE.txt

        The first line renders differently because:

        Of course, if there's something better, I'd love to see it...

        Anyway, I'll be quiet now so others can speak. :)

      • homotechsual
        homotechsual @homotechsual ·
        Author Owner

        Created by: seancolsen

        Based on the comments thus far, I propose adding the following content (everything below) to the Style Guide. I'm open to changing this. I just wrote it up so that we have something concrete to help move this issue forward.

        Displaying shell commands

        Example of correct usage

        1. Create a new buildkit site with Drupal 7.x and CiviCRM master

          civibuild create drupal-demo --civi-ver master --url http://localhost:8001

        2. Go to the civicrm directory within the site you just created.

          cd ~/buildkit/build/drupal-demo/sites/all/modules/civicrm

          Note: this directory will vary depending on where you have installed buildkit.

        3. Create a fork of civicrm-core on github.com for publishing your changes

          hub fork

          Note: At this point you can see that, because of the previous command, your local civicrm repo is now set up to track two separate remote repos — the one owned by CiviCRM, and the one owned by you (which hub just created):

          $ git remote -v
origin  https://github.com/civicrm/civicrm-core.git (fetch)
origin  https://github.com/civicrm/civicrm-core.git (push)
yourusername      git@github.com:yourusername/civicrm-core.git (fetch)
yourusername      git@github.com:yourusername/civicrm-core.git (push)

        4. (Tutorial truncated here to keep this example brief)

        Guidelines

        • Do not display comments in shell commands. Instead move your commentary outside of the code block so that it displays as regular paragraph text.
        • Always keep each shell command in its own code block. Use separate code blocks for separate commands, with paragraph text between the code blocks to explain the steps.
        • When you don't want to display output from the command (the most common scenario), do not display a command prompt (e.g $ ) before the command.
        • When you do want to display command output to the reader, include the output in the same code block as the command, and prefix the command with $ to serve as a command prompt.
        • When it is crucial for the user to understand the directory in which to run the command, include a separate code block before hand with a cd command.
      • homotechsual
        homotechsual @homotechsual ·
        Author Owner

        Created by: nganivet

        +1 on these, although I would hate to go back to all existing pages to enforce these. So let's ease down on enforcement.

      • homotechsual
        homotechsual @homotechsual ·
        Author Owner

        Created by: totten

        I'm OK with deprecating comments for bash instructions (in favor of interleaved text). Reflecting, the comments were originally a workaround (eg I remember having trouble with interleaved bullet points and code snippets). Your example shows that working nicely with Github's renderer.

      • homotechsual
        homotechsual @homotechsual ·
        Author Owner

        Created by: seamuslee001

        @seanmadsen i feel like we have some pretty clear structure with those guidelines, I would also note that i think in some of the recent bash stuff i put in i followed those guidelines iirc

      • homotechsual
        homotechsual @homotechsual ·
        Author Owner

        Created by: seancolsen

        Yeah. but :grimacing: ummm, I think I've changed my mind since writing that large proposal above. :confused: This is one of the things I was hoping to address during a docs meeting (which I'm still working on planning).

        Now, I actually think that it is easiest if we always use dollar sign prefixes. I can explain more about this.

        For comparison the Docker docs style guide says:

        Start typed commands with $ (dollar space), so that they are easily differentiated from program output.

        I still like the idea of recommending that we avoid comments in shell commands. But I think that using a dollar sign is the best way to be consistent.

      • homotechsual
        homotechsual @homotechsual ·
        Author Owner

        Created by: seancolsen

        Revised proposal

        Building off of my last comment, I propose adding the following content (everything below) to the Style Guide.

        Displaying shell commands

        Example of correct usage

        1. Create a new buildkit site with Drupal 7.x and CiviCRM master

          $ cd ~/buildkit/build/drupal-demo/sites/all/modules/civicrm
$ civibuild create drupal-demo --civi-ver master --url http://localhost:8001

        2. Create a fork of civicrm-core on github.com for publishing your changes

          $ hub fork

          Note: At this point you can see that, because of the previous command, your local civicrm repo is now set up to track two separate remote repos — the one owned by CiviCRM, and the one owned by you (which hub just created):

          $ git remote -v
origin  https://github.com/civicrm/civicrm-core.git (fetch)
origin  https://github.com/civicrm/civicrm-core.git (push)
yourusername      git@github.com:yourusername/civicrm-core.git (fetch)
yourusername      git@github.com:yourusername/civicrm-core.git (push)

        3. (Tutorial truncated here to keep this example brief)

        Guidelines

        • Do not display comments in shell commands. Instead move your commentary outside of the code block so that it displays as regular paragraph text.
        • When possible, keep each shell command in its own code block.
        • Always prefix shell commands with a dollar sign $
        • When it is crucial for the user to understand the directory in which to run the command, include a separate code block before hand with a cd command.
      • homotechsual
        homotechsual @homotechsual ·
        Author Owner

        Created by: seancolsen

        Also to be clear:

        • Right now we have nothing in the style guide, so any style is fine
        • I think it's fine to add things to the style guide, even if our current docs aren't consistent. The style guide can apply to newly-written doc only. Plus I think it'll be pretty easy to clean up existing code blocks. They're easy to find with grep and there aren't too many of them.
      • homotechsual
        homotechsual @homotechsual ·
        Author Owner

        Created by: seamuslee001

        Now that PR #410 has been merged this can be closed

      Please register or sign in to reply