ndwarshuis
/
org-mode
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

org-manual: Improve and relocate linter documentation 

* doc/org-manual.org (Org Syntax): Move to "Miscellaneous".  Expound
  documentation about how to use the linter.

The syntax happens too early in the manual, before most elements are
even described.
This commit is contained in:
Nicolas Goaziou 2018-07-04 22:11:55 +02:00
parent b3e00f0c53
commit 53ec5f0a05
1 changed files with 45 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
doc/org-manual.org
View File

@ -1370,34 +1370,6 @@ The following command handles footnotes:
reference, and you can use the usual commands to follow these
links.
** Org Syntax
:PROPERTIES:
:DESCRIPTION: Formal description of Org's syntax.
:END:
A reference document providing a formal description of Org's syntax is
available as [[https://orgmode.org/worg/dev/org-syntax.html][a draft on Worg]], written and maintained by Nicolas
Goaziou. It defines Org's core internal concepts such as =headlines=,
=sections=, =affiliated keywords=, =(greater) elements= and =objects=.
Each part of an Org file falls into one of the categories above.
To explore the abstract structure of an Org buffer, run this in
a buffer:
: M-: (org-element-parse-buffer) <RET>
#+texinfo: @noindent
It outputs a list containing the buffer's content represented as an
abstract structure. The export engine relies on the information
stored in this list. Most interactive commands---e.g., for structure
editing---also rely on the syntactic meaning of the surrounding
context.
#+cindex: syntax checker
#+cindex: linter
#+findex: org-lint
You can check syntax in your documents using ~org-lint~ command.
* Tables
:PROPERTIES:
:DESCRIPTION: Pure magic for quick formatting.
@ -19229,6 +19201,51 @@ specifying the respective key as property =CRYPTKEY=, e.g.:
Excluding the =crypt= tag from inheritance prevents already encrypted
text from being encrypted again.
** Org Syntax
:PROPERTIES:
:DESCRIPTION: Formal description of Org's syntax.
:END:
A reference document providing a formal description of Org's syntax is
available as [[https://orgmode.org/worg/dev/org-syntax.html][a draft on Worg]], written and maintained by Nicolas
Goaziou. It defines Org's core internal concepts such as "headlines",
"sections", "affiliated keywords", "(greater) elements" and "objects".
Each part of an Org document belongs to one of the previous
categories.
To explore the abstract structure of an Org buffer, run this in
a buffer:
: M-: (org-element-parse-buffer) <RET>
#+texinfo: @noindent
It outputs a list containing the buffer's content represented as an
abstract structure. The export engine relies on the information
stored in this list. Most interactive commands---e.g., for structure
editing---also rely on the syntactic meaning of the surrounding
context.
#+cindex: syntax checker
#+cindex: linter
#+findex: org-lint
You can probe the syntax of your documents with the command
: M-x org-lint <RET>
#+texinfo: @noindent
It runs a number of checks to find common mistakes. It then displays
their location in a dedicated buffer, along with a description and
a "trust level", since false-positive are possible. From there, you
can operate on the reports with the following keys:
#+attr_texinfo: :columns 0.22 0.78
| {{{kbd(C-j)}}}, {{{kbd(TAB)}}} | Display the offending line |
| {{{kbd(RET)}}} | Move point to the offending line |
| {{{kbd(g)}}} | Check the document again |
| {{{kbd(h)}}} | Hide all reports from the same checker |
| {{{kbd(i)}}} | Also remove them from all subsequent checks |
| {{{kbd(S)}}} | Sort reports by the column at point |
* Hacking
:PROPERTIES:
:DESCRIPTION: How to hack your way around.