Merge pull request #891 from cr7pt0gr4ph7/pull-request/improve-docs

Fix #848: Improve the documentation for the commands

.gitignore

@@ -183,5 +183,6 @@ docs/content/license.md
 docs/content/release-notes.md
 _NCrunch_Paket
 docs/content/paket-*.md
+!docs/content/paket-folder.md
 *.bak
 System.Management.Automation.dll

docs/content/commands/add.md

@@ -15,7 +15,7 @@ Consider the following paket.dependencies file:
 
 	nuget FAKE
 
-Now we run `paket add nuget xunit --interactive` install the package:
+Now we run `paket add nuget xunit --interactive` to install the package:
 
 ![alt text](img/interactive-add.png "Interactive paket add")
 

docs/content/commands/auto-restore.md

@@ -7,4 +7,4 @@ Auto-restore on:
 Auto-restore off:
 
   - removes `paket.targets` from the `.paket` directory,
-  - removes the `<Import>` statement for `paket.targets` from projects that have the [references file](references-files.html).
+  - removes the `<Import>` statement for `paket.targets` from projects that have the [references file](references-files.html).

docs/content/commands/config.md

@@ -1,9 +1,15 @@
-Paket will then ask for username and password.
+## Adding credentials
 
-This credentials will be used if no username and password for the source are configured in the [`paket.dependencies` file](nuget-dependencies.html).
+```batchfile
+paket config add-credentials SOURCEURL
+```
 
-The configuration file can be found in:
+Paket will then ask you for the username and password that will be used for the specified `SOURCEURL`.
+
+The credentials you enter here will then be used if no username and password for the source are configured in the [`paket.dependencies` file](nuget-dependencies.html).
+
+The configuration file can be found at:
 
 	let AppDataFolder = Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData)
 	let PaketConfigFolder = Path.Combine(AppDataFolder, "Paket")
-	let PaketConfigFile = Path.Combine(PaketConfigFolder, "paket.config")
+	let PaketConfigFile = Path.Combine(PaketConfigFolder, "paket.config")

docs/content/commands/convert-from-nuget.md

@@ -19,13 +19,13 @@ The `paket convert-from-nuget` command:
 ## Migrating NuGet source credentials
 
 If you are using authorized NuGet feeds, convert-from-nuget command will automatically migrate the credentials for you.
-Following are valid modes for `--creds-migration` option:
+Following are valid modes for the `--creds-migration` option:
 
-1. `encrypt` -  Encrypt your credentials and save in [paket configuration file](paket-config-file.html).
-2. `plaintext` - Include your credentials in plaintext in paket.dependencies file. See [example](nuget-dependencies.html#plaintext-credentials)
-3. `selective` - Use this switch, if you're using more than one authorized NuGet feed, and want to apply different mode for each of them.
+1. `encrypt` -  Encrypt your credentials and save them in the [paket configuration file](paket-config-file.html).
+2. `plaintext` - Include your credentials in plaintext in the paket.dependencies file. See [example](nuget-dependencies.html#plaintext-credentials).
+3. `selective` - Use this switch if you're using more than one authorized NuGet feed, and you want to apply different modes for each of them.
 
 ## Simplify direct dependencies
 
 After converting your solution from NuGet, you may end up with many transitive dependencies in your Paket files.
-Consider using [`paket simplify`](paket-simplify.html) to remove unnecessary transitive dependencies from your paket.dependencies file and paket.references files.
+Consider using [`paket simplify`](paket-simplify.html) to remove unnecessary transitive dependencies from your paket.dependencies and paket.references files.

docs/content/commands/find-package-versions.md

@@ -1,9 +1,10 @@
 ## Sample
 
 Running the command:
-
-	paket find-package-versions name FAKE -s max 10
+
+    [lang=batchfile]
+    paket find-package-versions name FAKE -s max 10
 
 will result in:
 
-![alt text](img/paket-find-package-versions.png "paket find-package-versions command")
+![alt text](img/paket-find-package-versions.png "paket find-package-versions command")

docs/content/commands/find-packages.md

@@ -1,8 +1,9 @@
 ## Sample
 
 Running the command:
-
-	paket find-packages
+
+    [lang=batchfile]
+    paket find-packages
 
 and then enter search text and press enter:
 
@@ -11,7 +12,8 @@ and then enter search text and press enter:
 ## Silent mode
 
 The silent mode can be used for additional tooling support in various editors. It allows to create suggestions for `paket add`:
-
-	paket find-packages -s
 
-The command allows runs to suggest package names. It will keep in a loop until it receives the text ":q". 
+    [lang=batchfile]
+    paket find-packages -s
+
+The command allows runs to suggest package names. It will keep running in a loop until it receives the text ":q".

docs/content/commands/find-refs.md

@@ -2,24 +2,25 @@
 
 *.src/Paket/paket.references* contains:
 
-	UnionArgParser
-	FSharp.Core
+    UnionArgParser
+    FSharp.Core
 
 *.src/Paket.Core/paket.references* contains:
 
-	Newtonsoft.Json
-	DotNetZip
-	FSharp.Core
+    Newtonsoft.Json
+    DotNetZip
+    FSharp.Core
 
 Now we run
-
-	paket find-refs DotNetZip FSharp.Core
+
+    [lang=batchfile]
+    paket find-refs DotNetZip FSharp.Core
 
 and paket gives the following output:
-
-	DotNetZip
-	.src/Paket.Core/Paket.Core.fsproj
 
-	FSharp.Core
-	.src/Paket.Core/Paket.Core.fsproj
-	.src/Paket/Paket.fsproj
+    DotNetZip
+    .src/Paket.Core/Paket.Core.fsproj
+
+    FSharp.Core
+    .src/Paket.Core/Paket.Core.fsproj
+    .src/Paket/Paket.fsproj

docs/content/commands/install.md

@@ -0,0 +1,8 @@
+# [after-command]
+
+If the paket.dependencies file has been changed since the last update of the paket.lock file (e.g. added dependencies or changed version requirements),
+Paket will update the paket.lock file to make it match paket.dependencies again.
+
+Unlike [`paket update`](paket-update.html), [`paket install`](paket-install.html) will only look for
+new versions of dependencies that have been modified in paket.dependencies,
+and use the version from paket.lock for all other dependencies.

docs/content/commands/outdated.md

@@ -18,4 +18,4 @@ and the following paket.lock file:
 
 Now we run `paket outdated`:
 
-![alt text](img/paket-outdated.png "paket outdated command")
+![alt text](img/paket-outdated.png "paket outdated command")

docs/content/commands/remove.md

@@ -5,4 +5,4 @@ It's also possible to remove a package from a specified project only:
     [lang=batchfile]
     $ paket remove nuget PACKAGENAME [project PROJECT] [--force] [--hard]
 
-See also [paket add](paket-add.html).
+See also [paket add](paket-add.html).

docs/content/commands/restore.md

@@ -0,0 +1,4 @@
+# [after-command]
+
+`paket restore` fails with an error if the paket.lock file does not exist.
+No packages are downloaded in that case. Please see `paket install` and `paket update` to learn how to create the paket.lock file.

docs/content/commands/show-installed-packages.md

@@ -1,9 +1,10 @@
 ## Sample
 
 Running the command:
-
-	paket show-installed-packages --all -s
+
+    [lang=batchfile]
+    paket show-installed-packages --all -s
 
 will result in:
 
-![alt text](img/paket-show-installed-packages.png "paket show-installed-packages command")
+![alt text](img/paket-show-installed-packages.png "paket show-installed-packages command")

docs/content/commands/simplify.md

@@ -45,4 +45,4 @@ The simplify command will help you maintain your direct dependencies.
 ## Interactive mode
 
 Sometimes, you may still want to have control over some of the transitive dependencies. In this case you can use the `--interactive` flag,
-which will ask you to confirm before deleting a dependency from a file.
+which will ask you to confirm before deleting a dependency from a file.

docs/content/commands/update.md

@@ -1,12 +1,44 @@
+## Updating all packages
+
+If you do not specify a package, then all packages from paket.dependencies are updated.
+
+    [lang=batchfile]
+    paket update [--force|-f] [--hard] [--redirects] [--no-install]
+
+First, the current [`paket.lock` file](lock-file.html) is deleted. `paket update` then recomputes the current dependency resolution,
+as explained under [Package resolution algorithm](http://fsprojects.github.io/Paket/resolver.html), and writes it to paket.lock.
+It then proceeds to download the packages and to install them into the projects.
+
+Please see [`paket install`](paket-install.html) if you want to keep the current versions from your paket.lock file.
+
+### Options:
+
+  `--force [-f]`: Forces the download and reinstallation of all packages.
+
+  `--hard`: Replaces package references within project files even if they are not yet adhering to the Paket's conventions (and hence considered manually managed). See [convert from NuGet](paket-convert-from-nuget.html).
+
+  `--redirects`: Creates binding redirects for the NuGet packages.
+
+  `--no-install`: Skips paket install --hard process afterward generation of [`paket.lock` file](lock-file.html).
+
+
 ## Updating a single package
 
 It's also possible to update only a single package and to keep all other dependencies fixed:
 
     [lang=batchfile]
-    $ paket update nuget PACKAGENAME [version VERSION] [--force] [--hard]	
+    paket update nuget PACKAGENAME [version VERSION] [--force|-f] [--hard] [--redirects] [--no-install]
+
+### Options:
+
+  `nuget <string>`: Nuget package id
+
+  `version <string>`: Allows to specify version of the package.
+
+  `--force [-f]`: Forces the download and reinstallation of all packages.
 
-Options:
+  `--hard`: Replaces package references within project files even if they are not yet adhering to the Paket's conventions (and hence considered manually managed). See [convert from NuGet](paket-convert-from-nuget.html).
 
-  `--force`: Forces the download and reinstallation of all packages.
+  `--redirects`: Creates binding redirects for the NuGet packages.
 
-  `--hard`: Replaces package references within project files even if they are not yet adhering to to Paket's conventions (and hence considered manually managed). See [convert from NuGet](paket-convert-from-nuget.html).
+  `--no-install`: Skips paket install --hard process afterward generation of [`paket.lock` file](lock-file.html).

docs/tools/generate.fsx

@@ -12,7 +12,9 @@ Paket.Commands.getAllCommands()
         if File.Exists optFile
         then File.ReadAllText optFile
         else ""
-    File.WriteAllText(sprintf "../content/paket-%s.md" command.Name, Paket.Commands.markdown command additionalText))
+    // Work around bug tpetricek/FSharp.Formatting#321 (FSharp.Literate does not escape HTML entities in code blocks with unknown language)
+    let cleanText (text : string) = text.Replace("[lang=batchfile]", "[lang=msh]").Replace("```batchfile", "```msh")
+    File.WriteAllText(sprintf "../content/paket-%s.md" command.Name, Paket.Commands.markdown command additionalText |> cleanText))
 #endif
 
 

docs/tools/templates/template.cshtml

@@ -18,6 +18,30 @@
     <!--[if lt IE 9]>
       <script src="https://html5shim.googlecode.com/svn/trunk/html5.js"></script>
     <![endif]-->
+    <style type="text/css">
+      table.pre td.lines {
+        vertical-align: top;
+      }
+      pre.fssnip code[lang=batchfile],
+      pre.fssnip code[lang=msh] {
+        display: inline-block;
+        white-space: pre-wrap;       /* CSS 3 */
+        white-space: -moz-pre-wrap;  /* Mozilla, since 1999 */
+        white-space: -pre-wrap;      /* Opera 4-6 */
+        white-space: -o-pre-wrap;    /* Opera 7 */
+        word-wrap: break-word;       /* Internet Explorer 5.5+ */
+        word-break: keep-all;
+        padding-left: 2em;
+        text-indent: -2em;
+      }
+    </style>
+    <script type="text/javascript">
+      $(function() {
+        $("code[lang='batchfile'], code[lang='msh']").each(function() {
+          $(this).html($(this).html().replace(/ &lt;/g, "&nbsp;&lt;"))
+        })
+      })
+    </script>
   </head>
   <body>
     <div class="container">