Merge lp:~dholbach/snapcraft/doc-fixes into lp:~snappy-dev/snapcraft/core

[Daniel Holbach]

Small doc markup fixes.

Small doc markup fixes.

[Simon Eisenmann (longsleep)]

Yay! This cleans up with the special characters somebody did put in the comments. This should be merged asap.

review: Approve

[Sergio Schvezov (sergiusens)]

review: Approve

[lp:~dholbach/snapcraft/doc-fixes]

121. By Daniel Holbach on 2015-08-05

Add some next steps. by dholbach approved by sergiusens,longsleep

122. By Daniel Holbach on 2015-08-05

Small doc markup fixes. by dholbach approved by sergiusens,longsleep

=== modified file 'docs/intro.md'
--- docs/intro.md	2015-07-29 16:48:14 +0000
+++ docs/intro.md	2015-08-05 11:47:29 +0000
@@ -6,8 +6,8 @@
 
 # Snappy
 
-Snappy Ubuntu Core is a new rendition of Ubuntu with transactional updates — a
-minimal server image with the same libraries as today’s Ubuntu, but
+Snappy Ubuntu Core is a new rendition of Ubuntu with transactional updates - a
+minimal server image with the same libraries as today's Ubuntu, but
 applications are provided through a simpler mechanism.
 
 Snappy apps and Ubuntu Core itself can be upgraded atomically and rolled back
@@ -16,18 +16,18 @@
 
 # Key concepts
 
-A .snap package for the Ubuntu Core system contains all its
+A `.snap` package for the Ubuntu Core system contains all its
 dependencies. This has a couple of advantages over traditional deb or
 rpm based dependency handling, the most important being that a
 developer can always be assured that there are no regressions triggered by
 changes to the system underneath their app.
 
 Snapcraft makes bundling these dependencies easy by allowing you to
-specify them as “parts” in the snapcraft.yaml file.
+specify them as "parts" in the `snapcraft.yaml` file.
 
 ## Parts
 
-A central aspect of a snapcraft recipe is a “part”. A part is a piece
+A central aspect of a snapcraft recipe is a "part". A part is a piece
 of software or data that the snap package requires to work or to
 build other parts. Each part is managed by a snapcraft plugin and parts
 are usually independent of each other.
@@ -47,46 +47,46 @@
 
 The first is that each part is pulled. This step will download
 content, e.g. checkout a git repository or download a binary component
-like the Java SDK. Snapcraft will create a parts/ directory with
-sub-directories like parts/part-name/src for each part that contains
+like the Java SDK. Snapcraft will create a `parts/` directory with
+sub-directories like `parts/part-name/src` for each part that contains
 the downloaded content.
 
 #### Build
 
-The next step is that each part is built in its parts/part-name/build
-directory and installs itself into parts/part-name/install.
+The next step is that each part is built in its `parts/part-name/build`
+directory and installs itself into `parts/part-name/install`.
 
 ### Stage
 
 After the build of each part the parts are combined into a single
-directory tree that is called the “staging area”. It can be found
-under the ./stage directory.
+directory tree that is called the "staging area". It can be found
+under the `./stage` directory.
 
-This ./stage directory is useful for building outside code that isn’t in the
-snapcraft.yaml recipe against the snap contents. For example, you might build a
-local project against the libraries in ./stage by running
+This `./stage` directory is useful for building outside code that isn't in the
+`snapcraft.yaml` recipe against the snap contents. For example, you might build a
+local project against the libraries in `./stage` by running
 `snapcraft shell make`. Though in general, you are encouraged to add even local
 projects to snapcraft.yaml with a local `source:` path.
 
 ### Snap
 
-The snap step moves the data into a ./snap directory. It contains only
+The snap step moves the data into a `./snap` directory. It contains only
 the content that will be put into the final snap package, unlike the staging
 area which may include some development files not destined for your package.
 
 The Snappy metadata information about your project will also now be placed in
-./snap/meta.
+`./snap/meta`.
 
-This ./snap directory is useful for inspecting what is going into your snap
-and to make any final post-processing on snapcraft’s output.
+This `./snap` directory is useful for inspecting what is going into your snap
+and to make any final post-processing on snapcraft's output.
 
 ### Assemble
 
-The final step builds a snap package out of the snap directory. This .snap file
+The final step builds a snap package out of the `snap` directory. This `.snap` file
 can be uploaded to the Ubuntu Store and published directly to Snappy users.
 
 # Next
 
 After introducing the key concept of snapcraft it is probably a good
-time to look at the tutorial in docs/tutorial.md to see how it works
+time to look at [the tutorial](tutorial.md) to see how it works
 for an example project.

=== modified file 'docs/tutorial.md'
--- docs/tutorial.md	2015-07-29 14:40:11 +0000
+++ docs/tutorial.md	2015-08-05 11:47:29 +0000
@@ -40,9 +40,9 @@
         panic(http.ListenAndServe(":8080", http.FileServer(http.Dir("."))))
     }
 
-This will serve the current directory on port :8080. If there is an index.html
-in the current directory, it will be served. Otherwise a directory listing will
-be shown.
+This will serve the current directory on port `:8080`. If there is an 
+`index.html` in the current directory, it will be served. Otherwise a 
+directory listing will be shown.
 
 I've provided the above code in a simple GitHub
 [repository](https://github.com/mikix/golang-static-http).
@@ -91,8 +91,8 @@
 
 You'll see a bunch of output, including Snapcraft downloading the Go compiler.
 It will use this to compile the code found on GitHub. Eventually when it is
-done, you'll be able to inspect the ./stage folder and see the web server
-executable sitting in ./stage/bin:
+done, you'll be able to inspect the `./stage` folder and see the web server
+executable sitting in `./stage/bin`:
 
     $ ls stage/bin
     golang-static-http
@@ -117,11 +117,11 @@
 
     $ snapcraft stage
 
-You'll note that Snapcraft skipped downloading and building golang-static-htpp
-again because it knew it had already done so.
+You'll note that Snapcraft skipped downloading and building 
+`golang-static-htpp` again because it knew it had already done so.
 
 You'll also see Snapcraft downloading and unpacking all the Ubuntu packages
-into your snap. If you look at ./stage, you'll see a lot more files now:
+into your snap. If you look at `./stage`, you'll see a lot more files now:
 
     $ ls stage
     bin  etc  lib  usr  var
@@ -164,7 +164,7 @@
 
 The `copy` plugin takes a list of files to just directly copy without building
 or downloading anything. In this case, we just want to put our glue script in
-the bin/ directory.
+the `bin/` directory.
 
 If we run Snapcraft again, we won't be surprised: