Home | History | Annotate | only in /ndk/docs/tools
Up to higher level directory
NameDateSize
ndk-markdown-substitutions.py06-Dec-20137.7K
README06-Dec-20132.2K

README

      1 This directory contains the following documentation-related tools:
      2 
      3 ndk-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 
     53 Important 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 
     63 Apart from that, the input format of NDK .text file is regular Markdown
     64 for now. In the future, using the Python Markdown Extensions API might
     65 result in a completely different script that could allow for more custom
     66 markup and/or better HTML output, but the current state is pretty good
     67 and lends itself to CSS-ification.
     68