You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# XOS documentation on [guide.xosproject.org](https://guide.xosproject.org)
2
2
3
-
This documentation uses [GitHub Pages](https://pages.github.com), specifically the [Jekyll Integration](https://help.github.com/articles/using-jekyll-with-pages/), which can be deployed using [Bundler](http://bundler.io/).
3
+
This documentation uses [GitHub Pages](https://pages.github.com), specifically the [Jekyll Integration](https://help.github.com/articles/using-jekyll-with-pages/), which can be deployed using [Bundler](http://bundler.io/).
4
4
5
5
## Previewing a local copy during editing
6
6
7
7
To set up github-pages flavored Jekyll, `bundle install --path ../github-pages` in the repo root, which creates a bundle of gems in the parent directory that are current with the ones GitHub uses to render the site from it's repo.
8
8
9
9
To view the local edits: `bundle exec jekyll serve`, then visit http://localhost:4000 .
10
10
11
+
Note that you will have to restart this command if you modify the `_config.yml` file that contains the Jekyll configuration.
12
+
11
13
## Style notes
12
14
13
-
When quoting a section of text inline, such as method or variable names, filenames and paths, commands, and similar, use the backtick (`` ` ``) character. One exception - when creating a URL for a filename/path link that points to that location in the code repo, quoting isn't needed.
15
+
*Quoting Text*: When quoting a section of text inline, such as method or variable names, filenames and paths, commands, and similar, use the backtick (`` ` ``) character, except when creating a URL for a filename/path link that points to that location in the code repo in which case quoting isn't needed.
16
+
17
+
*Code*: For standalone or multi-line code snippets, wrap code in tags for [Jekyll's code highlighting support](http://jekyllrb.com/docs/posts/#highlighting-code-snippets), which looks like this :
18
+
```
19
+
{% highlight sh %}
20
+
Code in shell script
21
+
{% endhighlight %}
22
+
```
23
+
24
+
If you're quoting a template that uses the same `{% %}` tags as Jekyll, you may need to [escape the code as described here](http://stackoverflow.com/questions/3426182/how-to-escape-liquid-template-tags).
14
25
15
-
For standalone or multi-line code snippets, wrap code in tags for [Jekyll's code highlighting support](http://jekyllrb.com/docs/posts/#highlighting-code-snippets). You do not need to add additional indentation to the code.
26
+
*Shell Commands*: For shell commands that are intended to be run interactively by a user, prefix line with `$` if run as a unprivileged user, or `#` if being run as root. Put a space between the prefix and the command. If you need to specify which user is running a commands, or on which host, add that to the prefix (ex: `username@host $`).
16
27
17
-
For shell commands that are intended to be run interactively by a user, prefix each line with `$` if run as a unprivledged user, or `#` if being run as root. Put a space between the prefix and the command. If you need to specify which user is running a commands, or on which host, add that to the prefix (ex: `username@host $`).
28
+
*Figures/Images*: When embedding figures:
18
29
19
-
When embedding figures, name the image file with a prefix of the section where it's being used, place in `/figures`, and then use the Jekyll `include` command to add it with the figure template and a caption/alttext:
30
+
1. Name the image file with a prefix of the page where it's being used,
31
+
2. Optionally prefix it with the figure number and a description.
32
+
3. Place in `/figures`
33
+
4. Use the Jekyll `include` command to add it with the figure template and a caption/alttext:
20
34
21
35
```
22
-
{% include figure.html url="/figures/archguide-fig02_service_anatomy.jpg" caption="Figure 2. Anatomy of a Service." %}
36
+
{% include figure.html url="/figures/archguide-fig02_service_anatomy.jpg" caption="Figure 2. Anatomy of a Service." %}
23
37
```
38
+
39
+
## Converting documents to include in this repo
40
+
41
+
Note - all the below methods require a bit of cleanup after conversion, but should do the majority of the work for you
42
+
43
+
### PDF
44
+
45
+
The [Poppler](http://poppler.freedesktop.org) library includes the utilties `pdftotext` and `pdfimages`.
0 commit comments