Fix documentation

Restores erroneous changes to lexicon_filter and changes to doc_src/ pages. Done by hand to ensure version history. Fixes display of % when misinterpreted by Doxygen.
fish-shell · Jul 17, 2016 · b2be50f · b2be50f
1 parent 190fb4a
commit b2be50f
Show file tree

Hide file tree

Showing 8 changed files with 175 additions and 166 deletions.
diff --git a/doc_src/FORMATTING.md b/doc_src/FORMATTING.md
@@ -1,6 +1,6 @@
 # Formatting guide for fish docs
 
-The fish documentation has been updated to support Doxygen 1.8.7+, and while the main benefit of this change is extensive Markdown support, the addition of a fish lexicon and syntax filter, combined with semantic markup rules allows for automatic formatting enhancements across the HTML user_docs, the developer docs and the man pages.
+The fish documentation has been updated to support Doxygen 1.8.7+, and while the main benefit of this change is extensive Markdown support, the addition of a fish lexicon and syntax filter, combined with semantic markup rules allows for automatic formatting enhancements across the HTML user_docs and man pages.
 
 Initially my motivation was to fix a problem with long options ([Issue #1557](https://github.com/fish-shell/fish-shell/issues/1557) on GitHub), but as I worked on fixing the issue I realised there was an opportunity to simplify, reinforce and clarify the current documentation, hopefully making further contribution easier and cleaner, while allowing the documentation examples to presented more clearly with less author effort.
 
@@ -60,14 +60,10 @@ which is then transformed by Doxygen into an HTML version (`make doc`):
 
 `<span class="command">echo</span> <span class="argument">hello</span> <span class="argument">world</span>`
 
-A man page version (`make share/man`):
+And a man page version (`make share/man`):
 
 __echo__ hello world
 
-And a simple HTML version for the developer docs (`make doc`) and the LATEX/PDF manual  (`make doc/refman.pdf`):
-
-`echo hello world`
-
 ### Fonts
 
 In older browsers, it was easy to set the fonts used for the three basic type styles (serif, sans-serif and monospace). Modern browsers have removed these options in their respective quests for simplification, assuming the content author will provide suitable styles for the content in the site's CSS, or the end user will provide overriding styles manually. Doxygen's default styling is very simple and most users will just accept this default.
@@ -154,22 +150,25 @@ The following can be used in \\fish blocks to render some fish scenarios. These
 
 ### Custom formatting tags
 
-- `{{` and `}}`: Required when wanting curly braces in regular expression example.
-- `\\asis`: \\asis\{This text will not be parsed for fish markup.\}
-- `\\bksl`: \\bksl\{Render the contents with a preceding backslash. Useful when presenting output.}
-- `\\eror`: \\eror\{This would be shown as an error.\}
-- `\\mtch`: \\mtch\{Matched\} items, such as tab completions.
-- `\\outp`: \\outp\{This would be rendered as command/script output.\}
-- `\\sgst`: auto\\sgst\{suggestion\}.
-- `\\smtc`: Matched items \\smtc\{searched\} for, like grep results.
-- `\\undr`: \\undr\{These words are underlined\}.
+```html
+<u>: <u>These words are underlined.</u>
+<s>: auto<s>suggestion</s>.
+<m>: <m>Matched</m> items, such as tab completions.
+<sm>: Matched items <sm>searched</sm> for, like grep results.
+<bs>: Render the contents with a preceding backslash. Useful when presenting output.
+<error>: <error>This would be shown as an error.</error>
+<asis>: <asis>This text will not be parsed for fish markup.</asis>
+<outp>: <outp>This would be rendered as command/script output.</outp>
+{{ and }}: Required when wanting curly braces in regular expression example.
+```
 
 ### Prompts and cursors
 
-- `>_`: Display a basic prompt.
-- `~>_`: Display a prompt with a the home directory as the current working directory.
-- `___` (3 underscores): Display a cursor.
-
+```html
+>_: Display a basic prompt.
+~>_: Display a prompt with a the home directory as the current working directory.
+___ (3 underscores): Display a cursor.
+```
 
 ### Keyboard shortcuts: @key{} and @cursor_key{}
 
@@ -251,15 +250,4 @@ end
 # NOT PORTABLE! Paths would be need to be updated on other systems.
 ```
 
-### Developer docs and LATEX/PDF output
-
-- HTML developer docs tested on Ubuntu 14.04, CentOS 6.5 and Mac OS X 10.9.
-- LATEX/PDF reference manual tested on Mac OS X 10.9 using MacTEX. PDF production returns an error (due to Doxygen's use of an outdated 'float' package), but manual PDF output is ok.
-
-### Future changes
-
-1. The documentation creation process would be better if it could be modularised further and moved out of the makefile into a number of supporting scripts. This would allow both the automake and Xcode build processes to use the documentation scripts directly. 
-2. Remove the Doxygen dependency entirely for the user documentation. This would be very acheivable now that the bulk of the documentation is in Markdown.
-3. It would be useful to gauge what parts of the documentation are actually used by users. Judging by the amount of 'missing comment' errors during the developer docs build phase, this aspect of the docs has been rather neglected. If it is not longer used or useful, then this could change the future direction of the documentation and significantly streamline the process.
-
 #### Author: Mark Griffiths [@GitHub](https://github.com/MarkGriffiths)
diff --git a/doc_src/fg.txt b/doc_src/fg.txt
@@ -9,7 +9,7 @@ fg [PID]
 
 `fg` brings the specified <a href="index.html#syntax-job-control">job</a> to the foreground, resuming it if it is stopped. While a foreground job is executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If PID is specified, the job with the specified group ID is put in the foreground.
 
-The PID of the desired process is usually found by using <a href="index.html#expand-process">process expansion</a>.
+The PID of the desired process is usually found by using <a href="index.html#expand-process">process expansion</a>. Fish is capable of expanding far more than just the numeric PID, including referencing itself and finding PIDs by name.
 
 
 \subsection fg-example Example

diff --git a/doc_src/index.hdr.in b/doc_src/index.hdr.in
@@ -70,7 +70,7 @@ rm "cumbersome filename.txt"
 Will remove the file 'cumbersome filename.txt', while
 
 \fish
-rm \asis{cumbersome filename.txt}
+rm <asis>cumbersome filename.txt</asis>
 \endfish
 
 would remove the two files 'cumbersome' and 'filename.txt'.
@@ -553,22 +553,22 @@ Lists adjacent to other lists or strings are expanded as cartesian products:
 Examples:
 \fish{cli-dark}
 >_ echo {good,bad}" apples"
-\outp{good apples bad apples}
+<outp>good apples bad apples</outp>
 
 >_ set -l a x y z
 >_ set -l b 1 2 3
 
 >_ echo $a$b
-\outp{x1 y1 z1 x2 y2 z2 x3 y3 z3}
+<outp>x1 y1 z1 x2 y2 z2 x3 y3 z3</outp>
 
 >_ echo $a"-"$b
-\outp{x-1 y-1 z-1 x-2 y-2 z-2 x-3 y-3 z-3}
+<outp>x-1 y-1 z-1 x-2 y-2 z-2 x-3 y-3 z-3</outp>
 
 >_ echo {x,y,z}$b
-\outp{x1 y1 z1 x2 y2 z2 x3 y3 z3}
+<outp>x1 y1 z1 x2 y2 z2 x3 y3 z3</outp>
 
 >_ echo {$b}word
-\outp{1word 2word 3word}
+<outp>1word 2word 3word</outp>
 \endfish
 
 Be careful when you try to use braces to separate variable names from text. The dangers noted in the last example above can be avoided by wrapping the variable in double quotes instead of braces (`echo "$b"word`).
@@ -639,7 +639,7 @@ This form of expansion is useful for commands like kill and fg, which take proce
 
 Example:
 
-`fg %ema` will search for a process whose command line begins with the letters 'ema', such as emacs, and if found, put it in the foreground.
+`fg %%ema` will search for a process whose command line begins with the letters 'ema', such as emacs, and if found, put it in the foreground.
 
 `kill -s SIGINT %3` will send the SIGINT signal to the job with job ID 3.
 

diff --git a/doc_src/prompt_pwd.txt b/doc_src/prompt_pwd.txt
@@ -16,16 +16,16 @@ To change the number of characters per path component, set $fish_prompt_pwd_dir_
 \fish{cli-dark}
 >_ cd ~/
 >_ echo $PWD
-\outp{/home/alfa}
+<outp>/home/alfa</outp>
 
 >_ prompt_pwd
-\outp{~}
+<outp>~</outp>
 
 >_ cd /tmp/banana/sausage/with/mustard
 >_ prompt_pwd
-\outp{/t/b/s/w/mustard}
+<outp>/t/b/s/w/mustard</outp>
 
 >_ set -g fish_prompt_pwd_dir_length 3
 >_ prompt_pwd
-\outp{/tmp/ban/sau/wit/mustard}
+<outp>/tmp/ban/sau/wit/mustard</outp>
 \endfish
diff --git a/doc_src/string.txt b/doc_src/string.txt
@@ -58,7 +58,7 @@ In general, special characters are special by default, so `a+` matches one or mo
 
 \fish{cli-dark}
 >_ string length 'hello, world'
-\outp{12}
+<outp>12</outp>
 
 >_ set str foo
 >_ string length -q $str; echo $status
@@ -68,125 +68,125 @@ In general, special characters are special by default, so `a+` matches one or mo
 
 \fish{cli-dark}
 >_ string sub --length 2 abcde
-\outp{ab}
+<outp>ab</outp>
 
 >_ string sub -s 2 -l 2 abcde
-\outp{bc}
+<outp>bc</outp>
 
 >_ string sub --start=-2 abcde
-\outp{de}
+<outp>de</outp>
 \endfish
 
 \fish{cli-dark}
 >_ string split . example.com
-\outp{example}
-\outp{com}
+<outp>example</outp>
+<outp>com</outp>
 
 >_ string split -r -m1 / /usr/local/bin/fish
-\outp{/usr/local/bin}
-\outp{fish}
+<outp>/usr/local/bin</outp>
+<outp>fish</outp>
 
 >_ string split '' abc
-\outp{a}
-\outp{b}
-\outp{c}
+<outp>a</outp>
+<outp>b</outp>
+<outp>c</outp>
 \endfish
 
 \fish{cli-dark}
 >_ seq 3 | string join ...
-\outp{1...2...3}
+<outp>1...2...3</outp>
 \endfish
 
 \fish{cli-dark}
 >_ string trim ' abc  '
-\outp{abc}
+<outp>abc</outp>
 
 >_ string trim --right --chars=yz xyzzy zany
-\outp{x}
-\outp{zan}
+<outp>x</outp>
+<outp>zan</outp>
 \endfish
 
 \fish{cli-dark}
 >_ echo \\x07 | string escape
-\bksl{cg}
+<bs>cg</bs>
 \endfish
 
 \subsection string-example-match-glob Match Glob Examples
 
 \fish{cli-dark}
 >_ string match '?' a
-\outp{a}
+<outp>a</outp>
 
 >_ string match 'a*b' axxb
-\outp{axxb}
+<outp>axxb</outp>
 
 >_ string match -i 'a??B' Axxb
-\outp{Axxb}
+<outp>Axxb</outp>
 
 >_ echo 'ok?' | string match '*\\?'
->_ \outp{ok?}
+>_ <outp>ok?</outp>
+\endfish
 
 \subsection string-example-match-regex Match Regex Examples
 
 \fish{cli-dark}
 >_ string match -r 'cat|dog|fish' 'nice dog'
-\outp{dog}
+<outp>dog</outp>
 
 >_ string match -r -v "c.*[12]" {cat,dog}(seq 1 4)
-\outp{dog1}
-\outp{dog2}
-\outp{cat3}
-\outp{dog3}
-\outp{cat4}
-\outp{dog4}
-\endfish
-
->_ string match -r '(\\d\\d?):(\\d\\d):(\\d\\d)' \asis{2:34:56}
-\outp{2:34:56}
-\outp{2}
-\outp{34}
-\outp{56}
+<outp>dog1</outp>
+<outp>dog2</outp>
+<outp>cat3</outp>
+<outp>dog3</outp>
+<outp>cat4</outp>
+<outp>dog4</outp>
+
+>_ string match -r '(\\d\\d?):(\\d\\d):(\\d\\d)' <asis>2:34:56</asis>
+<outp>2:34:56</outp>
+<outp>2</outp>
+<outp>34</outp>
+<outp>56</outp>
 
 >_ string match -r '^(\\w{{2,4}})\\g1$' papa mud murmur
-\outp{papa}
-\outp{pa}
-\outp{murmur}
-\outp{mur}
+<outp>papa</outp>
+<outp>pa</outp>
+<outp>murmur</outp>
+<outp>mur</outp>
 
 >_ string match -r -a -n at ratatat
-\outp{2 2}
-\outp{4 2}
-\outp{6 2}
+<outp>2 2</outp>
+<outp>4 2</outp>
+<outp>6 2</outp>
 
 >_ string match -r -i '0x[0-9a-f]{{1,8}}' 'int magic = 0xBadC0de;'
-\outp{0xBadC0de}
+<outp>0xBadC0de</outp>
 \endfish
 
 \subsection string-example-replace-literal Replace Literal Examples
 
 \fish{cli-dark}
 >_ string replace is was 'blue is my favorite'
-\outp{blue was my favorite}
+<outp>blue was my favorite</outp>
 
 >_ string replace 3rd last 1st 2nd 3rd
-\outp{1st}
-\outp{2nd}
-\outp{last}
+<outp>1st</outp>
+<outp>2nd</outp>
+<outp>last</outp>
 
 >_ string replace -a ' ' _ 'spaces to underscores'
-\outp{spaces_to_underscores}
+<outp>spaces_to_underscores</outp>
 \endfish
 
 \subsection string-example-replace-Regex Replace Regex Examples
 
 \fish{cli-dark}
 >_ string replace -r -a '[^\\d.]+' ' ' '0 one two 3.14 four 5x'
-\outp{0 3.14 5}
+<outp>0 3.14 5</outp>
 
 >_ string replace -r '(\\w+)\\s+(\\w+)' '$2 $1 $$' 'left right'
-\outp{right left $}
+<outp>right left $</outp>
 
 >_ string replace -r '\\s*newline\\s*' '\\n' 'put a newline here'
-\outp{put a}
-\outp{here}
+<outp>put a</outp>
+<outp>here</outp>
 \endfish