1This directory contains the following documentation-related tools:
2
3ndk-markdown-substitutions.py:
4  A filter that takes Markdown text as input, and produces Markdown
5  test as output, but applies a few useful substitution.
6
7  Use with --run-checks to run the unit test suite.
8
9  For full list of substitutions, see the script, here's a quick summary:
10
11 * Links to documentation:
12     d/ANDROID-MK    -> [ANDROID-MK](ANDROID-MK.html)
13
14  To minimize changes to existing documentation, this also detects the
15  following in the input text and produces the same output:
16
17    ANDROID-MK.html
18    docs/ANDROID-MK.html
19    $NDK/docs/ANDROID-MK.html
20
21 * Links to bug entries:
22
23     b/<number>     ->  [b/<number>](http://b.android.com/<number>)
24
25   To minimize changes, also detects and rewrites:
26
27      http://b.android.com/<number>
28      http://http://code.google.com/p/android/issues/detail?id=<number>
29
30 * Links to gerrit patches:
31
32     r/<number>    -> [r/<number>](https://https://android-review.googlesource.com/#/c/<number>)
33
34   To minimize changes, also detects and rewrites:
35
36      https://android-review.googlesource.com/#/c/<number>
37
38 * Auto-formatting of various things to <code> format, e.g.:
39
40     LOCAL_XXX         ->  `LOCAL_XXX`
41     APP_XXX           ->  `APP_XXX`
42     script-name.sh    -> `script-name.sh`
43     -Option           -> `-Option`
44     -Option=value     -> `-Option=value`
45     __ANDROID__       -> `__ANDROID__`
46     __cxa_xxxx        -> `__cxa_xxxx`
47
48  * Automatic linkification:
49
50     http://example.com  ->   <http://example.com>
51
52
53Important note:
54  The script does not apply these subtitutions to line that begin with 8
55  spaces. This is to avoid modifying what will end up into code blocks in
56  the final
57
58  In other words, use 8, not 4 spaces to begin code blocks. This will
59  also shift them 4 spaces to the right in the HTML output, but this
60  is a good thing for readability anyway.
61
62
63Apart from that, the input format of NDK .text file is regular Markdown
64for now. In the future, using the Python Markdown Extensions API might
65result in a completely different script that could allow for more custom
66markup and/or better HTML output, but the current state is pretty good
67and lends itself to CSS-ification.
68