llvm-project/llvm/docs
Francis Visoiu Mistrih b213b27ee3 [YAML] Add support for non-printable characters
LLVM IR function names which disable mangling start with '\01'
(https://www.llvm.org/docs/LangRef.html#identifiers).

When an identifier like "\01@abc@" gets dumped to MIR, it is quoted, but
only with single quotes.

http://www.yaml.org/spec/1.2/spec.html#id2770814:

"The allowed character range explicitly excludes the C0 control block
allowed), the surrogate block #xD800-#xDFFF, #xFFFE, and #xFFFF."

http://www.yaml.org/spec/1.2/spec.html#id2776092:

"All non-printable characters must be escaped.
[...]
Note that escape sequences are only interpreted in double-quoted scalars."

This patch adds support for printing escaped non-printable characters
between double quotes if needed.

Should also fix PR31743.

Differential Revision: https://reviews.llvm.org/D41290

llvm-svn: 320996
2017-12-18 17:38:03 +00:00
..
CommandGuide [llvm-cov] Add an option for "export" command to emit only file summary data. 2017-12-11 23:17:46 +00:00
Frontend
HistoricalNotes
PDB
Proposals [LV] Model masking in VPlan, introducing VPInstructions 2017-11-20 12:01:47 +00:00
TableGen
_ocamldoc
_static
_templates
_themes/llvm-theme
tutorial [ORC][Kaleidoscope] Update ORCJit tutorial. 2017-09-17 00:24:43 +00:00
AMDGPUUsage.rst [AMDGPU] Rename Bonaire target to be gfx704; remove gfx800 and make Iceland and Tonga both use gfx802; update target feature handling 2017-12-12 05:47:00 +00:00
ARM-BE-bitcastfail.png
ARM-BE-bitcastsuccess.png
ARM-BE-ld1.png
ARM-BE-ldr.png
AdvancedBuilds.rst
AliasAnalysis.rst [docs] AliasAnalysis: clarify that PartialAlias doesn't enforce 2017-07-15 09:09:24 +00:00
Atomics.rst
Benchmarking.rst Add some tips on benchmarking. 2017-05-24 16:39:12 +00:00
BigEndianNEON.rst
BitCodeFormat.rst Hardware-assisted AddressSanitizer (llvm part). 2017-12-09 00:21:41 +00:00
BlockFrequencyTerminology.rst
BranchWeightMetadata.rst [Doc] Document prof metadata in LangRef 2017-06-15 15:57:12 +00:00
Bugpoint.rst [docs] Mention opt -metarenamer in the bugpoint docs 2017-11-15 18:05:19 +00:00
CFIVerify.rst Introduce the llvm-cfi-verify tool (resubmission of D37937). 2017-09-20 20:38:14 +00:00
CMake.rst [tools] Add option to install binutils symlinks 2017-11-02 21:43:32 +00:00
CMakeLists.txt [dsymutil][doc] Improve wording in manpage and rename file. 2017-11-02 18:44:54 +00:00
CMakePrimer.rst [docs] In the CMake primer, correct the description of the ARGV/ARGN variables. 2017-08-24 05:38:39 +00:00
CodeGenerator.rst [MC] Function stack size section. 2017-11-30 13:05:14 +00:00
CodeOfConduct.rst
CodingStandards.rst Update some code.google.com links 2017-11-13 23:47:58 +00:00
CommandLine.rst Remove references to response file argument in CommandLine.rst 2017-09-20 22:41:34 +00:00
CompileCudaWithLLVM.rst
CompilerWriterInfo.rst Fix broken links to the Itanium CXX ABI 2017-09-12 00:19:11 +00:00
Coroutines.rst fix trivial typos in documents; NFC 2017-07-02 12:44:27 +00:00
CoverageMappingFormat.rst [Coverage] Use gap regions to select better line exec counts 2017-09-18 23:37:28 +00:00
DebuggingJITedCode.rst
DeveloperPolicy.rst Fixed broken links in docs. 2017-09-22 21:10:37 +00:00
Docker.rst Made a script to build docker images easier to use. 2017-07-06 12:46:51 +00:00
ExceptionHandling.rst Fix broken links to the Itanium CXX ABI 2017-09-12 00:19:11 +00:00
ExtendedIntegerResults.txt
ExtendingLLVM.rst
Extensions.rst
FAQ.rst
FaultMaps.rst
FuzzingLLVM.rst [llvm-opt-fuzzer] Introduce llvm-opt-fuzzer for fuzzing optimization passes 2017-11-10 12:19:08 +00:00
GarbageCollection.rst
GetElementPtr.rst [docs] Update code block for compatibility with Sphinx 1.5.1 2017-11-06 11:47:24 +00:00
GettingStarted.rst docs/GettingStarted.rst: Update the list of release versions and tags 2017-11-30 23:47:30 +00:00
GettingStartedVS.rst [MC] Fix regression tests on Windows when git “core.autocrlf” is set to true. 2017-11-17 21:59:43 +00:00
GlobalISel.rst [globalisel] Add very brief docs summarizing the ISel part of the LLVMDev tutorial. 2017-10-23 17:18:44 +00:00
GoldPlugin.rst [docs] As of binutils 2.21.51.0.2, ld.bfd supports plugins too, represent this in docs 2017-06-23 13:54:10 +00:00
HowToAddABuilder.rst Added more info on silent master to the doc. 2017-07-05 20:45:44 +00:00
HowToBuildOnARM.rst
HowToCrossCompileBuiltinsOnArm.rst [docs][ARM] Add HowTo for cross compiling and testing compiler-rt builtins 2017-11-07 09:40:05 +00:00
HowToCrossCompileLLVM.rst
HowToReleaseLLVM.rst docs: Fix formatting in HowToReleaseLLVM 2017-09-19 03:27:26 +00:00
HowToSetUpLLVMStyleRTTI.rst
HowToSubmitABug.rst
HowToUseAttributes.rst
HowToUseInstrMappings.rst
InAlloca.rst
LLVMBuild.rst
LLVMBuild.txt
LangRef.rst Hardware-assisted AddressSanitizer (llvm part). 2017-12-09 00:21:41 +00:00
Lexicon.rst [Lexicon] Add "GEP" 2017-08-18 15:35:53 +00:00
LibFuzzer.rst [libFuzzer] add a flag -malloc_limit_mb 2017-12-01 22:12:04 +00:00
LinkTimeOptimization.rst
MCJIT-creation.png
MCJIT-dyld-load.png
MCJIT-engine-builder.png
MCJIT-load-object.png
MCJIT-load.png
MCJIT-resolve-relocations.png
MCJITDesignAndImplementation.rst
MIRLangRef.rst [CodeGen] Print MCSymbol operands as <mcsymbol sym> in both MIR and debug output 2017-12-14 10:03:23 +00:00
Makefile.sphinx
MarkedUpDisassembly.rst
MemorySSA.rst
MergeFunctions.rst
NVPTXUsage.rst [CodeGen] Unify MBB reference format in both MIR and debug output 2017-12-04 17:18:51 +00:00
OptBisect.rst
Packaging.rst
Passes.rst
Phabricator.rst docs/Phabricator: Better git examples to produce full context patches 2017-06-15 22:09:30 +00:00
ProgrammersManual.rst [docs] Code example fix 2017-10-24 10:23:10 +00:00
Projects.rst
README.txt Remove test commit change. 2017-06-24 20:13:32 +00:00
ReleaseNotes.rst [Debugify] Add a pass to test debug info preservation 2017-12-08 21:57:28 +00:00
ReleaseProcess.rst
ReportingGuide.rst
ScudoHardenedAllocator.rst [docs] Fix Scudo documentation error 2017-08-29 19:54:19 +00:00
SegmentedStacks.rst
SourceLevelDebugging.rst [docs] Update code block for compatibility with Sphinx 1.5.1 2017-11-06 11:47:24 +00:00
SphinxQuickstartTemplate.rst
StackMaps.rst
Statepoints.rst [docs] change a few code-blocks to llvm from text 2017-07-26 14:11:23 +00:00
SystemLibrary.rst
TableGenFundamentals.rst
TestSuiteMakefileGuide.rst
TestingGuide.rst Revert "lit.py: Add new %{shared_output(LABEL)} substitution" 2017-10-14 04:01:27 +00:00
TypeMetadata.rst Fixed broken links in docs. 2017-09-22 21:10:37 +00:00
Vectorizers.rst [docs] Update name of vectorization interleave flag. 2017-05-31 23:02:55 +00:00
WritingAnLLVMBackend.rst [Docs] Fix typo in scheduler model documentation. enumemation->enumeration 2017-12-10 09:14:35 +00:00
WritingAnLLVMPass.rst Fixed dead links in WritingAnLLVMPass.rst 2017-11-06 09:51:39 +00:00
XRay.rst [XRay][compiler-rt] Reduce XRay log spam 2017-12-13 06:37:13 +00:00
XRayExample.rst [XRay][compiler-rt] Reduce XRay log spam 2017-12-13 06:37:13 +00:00
XRayFDRFormat.rst [XRay][tools] Support tail-call exits before we write them in the runtime 2017-09-18 06:08:46 +00:00
YamlIO.rst [YAML] Add support for non-printable characters 2017-12-18 17:38:03 +00:00
conf.py Update trunk version to 6.0.0svn 2017-07-19 12:19:01 +00:00
doxygen-mainpage.dox
doxygen.cfg.in
gcc-loops.png
index.rst [docs][ARM] Add HowTo for cross compiling and testing compiler-rt builtins 2017-11-07 09:40:05 +00:00
linpack-pc.png
make.bat
re_format.7
yaml2obj.rst

README.txt

LLVM Documentation
==================

LLVM's documentation is written in reStructuredText, a lightweight
plaintext markup language (file extension `.rst`). While the
reStructuredText documentation should be quite readable in source form, it
is mostly meant to be processed by the Sphinx documentation generation
system to create HTML pages which are hosted on <http://llvm.org/docs/> and
updated after every commit. Manpage output is also supported, see below.

If you instead would like to generate and view the HTML locally, install
Sphinx <http://sphinx-doc.org/> and then do:

    cd <build-dir>
    cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_HTML=true <src-dir>
    make -j3 docs-llvm-html
    $BROWSER <build-dir>/docs//html/index.html

The mapping between reStructuredText files and generated documentation is
`docs/Foo.rst` <-> `<build-dir>/docs//html/Foo.html` <-> `http://llvm.org/docs/Foo.html`.

If you are interested in writing new documentation, you will want to read
`SphinxQuickstartTemplate.rst` which will get you writing documentation
very fast and includes examples of the most important reStructuredText
markup syntax.

Manpage Output
===============

Building the manpages is similar to building the HTML documentation. The
primary difference is to use the `man` makefile target, instead of the
default (which is `html`). Sphinx then produces the man pages in the
directory `<build-dir>/docs/man/`.

    cd <build-dir>
    cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_MAN=true <src-dir>
    make -j3 docs-llvm-man
    man -l >build-dir>/docs/man/FileCheck.1

The correspondence between .rst files and man pages is
`docs/CommandGuide/Foo.rst` <-> `<build-dir>/docs//man/Foo.1`.
These .rst files are also included during HTML generation so they are also
viewable online (as noted above) at e.g.
`http://llvm.org/docs/CommandGuide/Foo.html`.

Checking links
==============

The reachability of external links in the documentation can be checked by
running:

    cd docs/
    make -f Makefile.sphinx linkcheck

Doxygen page Output
==============

Install doxygen <http://www.stack.nl/~dimitri/doxygen/download.html> and dot2tex <https://dot2tex.readthedocs.io/en/latest>.

    cd <build-dir>
    cmake -DLLVM_ENABLE_DOXYGEN=On <llvm-top-src-dir>
    make doxygen-llvm # for LLVM docs
    make doxygen-clang # for clang docs

It will generate html in
    
    <build-dir>/docs/doxygen/html # for LLVM docs
    <build-dir>/tools/clang/docs/doxygen/html # for clang docs