Update docs for v1.5

Related: #4

.gitattributes

@@ -1,5 +1,5 @@
 # See: https://axvr.io/projects/ascribe/
-*       text=auto eol=lf final-newline
+*          text=auto eol=lf final-newline trim-trailing-whitespace
-*.vim   line-length=78 expand-tab tab-stop=4
+*.vim      line-length=78 expand-tab tab-stop=4
-doc/*   line-length=78 expand-tab tab-stop=4
+doc/*.txt  line-length=78 expand-tab tab-stop=4
-*.org   line-length=80 expand-tab tab-stop=4
+*.org      line-length=80 expand-tab tab-stop=4

.gitignore

@@ -0,0 +1 @@
+samples/

README.org

@@ -1,18 +1,15 @@
 #+TITLE: Org mode and Outline mode syntax highlighting for Vim
 
-Org.vim is a very minimal [[https://orgmode.org][Org mode]] and
+Org.vim is a minimal [[https://orgmode.org][Org mode]] and
 [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html][Outline mode]]
 plugin for [[https://www.vim.org][Vim]] providing only syntax highlighting and
 folding.
 
 This plugin aims to replicate Vim's [[https://github.com/tpope/vim-markdown/][existing Markdown]]
 editing experience on Org mode (and Outline mode) files, rather than trying to
-be a full featured Org mode plugin—that is what Emacs is for.
+be a full featured Org mode plugin—that is what Emacs is for.  Originally
-
+created so I could use [[https://github.com/orgzly/orgzly-android/][Orgzly]]
-Originally created so I would be able to quickly edit and easily read Org mode
+without worrying Emacs lock-in.
-files in Vim without any of /the bells and whistles/ of the original Emacs
-implementation.  It also allowed me use [[https://github.com/orgzly/orgzly-android/][Orgzly]]
-(highly recommended) without worrying about Emacs lock-in.
 
 *Note*: this project is considered /feature complete/ by the author, so the
 addition of new features will be unlikely.
@@ -31,6 +28,14 @@ git clone https://github.com/axvr/org.vim ~/.vim/pack/plugins/start/org
 vim +'helptags ~/.vim/pack/plugins/start/org/doc/' +q
 #+END_SRC
 
+Make sure the following options are set in your vimrc to enable all
+functionality:
+
+#+BEGIN_SRC vim
+syntax enable
+filetype plugin indent on
+#+END_SRC
+
 Once installed check out the Org.vim manual (run ~:help org.txt~ to open it) for
 usage information and configuration options.
 
@@ -46,7 +51,7 @@ Different Vim colour schemes will result in different appearances.
 
 ** Licence
 
-Copyright (c) 2018–2020, Alex Vear.
+Copyright © 2018–2020, Alex Vear.
 
 Org.vim is distributed under the same terms as Vim itself.
 

TODO

@@ -1,12 +1,12 @@
-MAYBE:
+* Future
   - Syntax highlight checkboxes and checkbox cookies
   - Separate syntax group for heading delimiters
-  - Syntax highlight and indent properties
+  - Syntax highlight and indent "properties"
-  - Hightlight concealed TeX the same as normal text
-  - Close inline block using same number of starting delimiters.
-  - Try to get text attributes to stack (e.g. underlined text in bold text)
-    - TeX math fragments in bold, italic, etc. text
-  - Set a max number of lines to search for end delimiter for bold/italic/etc. to 3 (might not be possible)
 
-UNLIKELY:
+* Maybe
   - Implement Emacs's abbreviations (e.g. '\<s<TAB>')
+
+* Impossible?
+  - Try to get text attributes to stack (e.g. underlined text in bold text)
+  - Close inline block using same number of starting delimiters.
+  - Set a max number of lines to search for end delimiter for bold/italic/etc. to 3 (might not be possible)

doc/org.txt

@@ -16,7 +16,7 @@ Welcome to the org.vim user manual.            *org*  *org.vim*  *vim-org*  *out
 ==============================================================================
  1. INTRODUCTION                                                    *org-intro*
 
-Org.vim is a very minimal Org mode [2] and Outline mode [1] plugin for Vim
+Org.vim is a minimal Org mode [2] and Outline mode [1] plugin for Vim
 providing only syntax highlighting and folding.
 
 This plugin aims to replicate Vim's existing Markdown editing experience on
@@ -37,6 +37,12 @@ enable it manually.
 >
     :set filetype=outline
 <
+Just make sure the following options are set in your vimrc to enable all
+functionality offered by this plugin:
+>
+    syntax enable
+    filetype plugin indent on
+<
 ==============================================================================
  3. CONFIGURATION                                           *org-configuration*
 
@@ -45,15 +51,10 @@ enable it manually.
 To control how Org.vim handles folding, just use the standard Vim |folding|
 options and commands.
 
-For example if you want to enable or disable folding, use 'foldenable'.
+For example if you want to enable or disable folding, just set 'foldenable'.
 >
     autocmd FileType org,outline setlocal nofoldenable
 <
-Or if you want folding enabled and all folds opened by default, use
-'foldlevelstart'.
->
-    autocmd FileType org,outline setlocal foldenable foldlevelstart=99
-<
 For more information on folding in Vim, refer to |fold.txt|.
 
 ------------------------------------------------------------------------------
@@ -127,9 +128,55 @@ To disable italics only in a single buffer, use this instead:
 >
     let b:org_use_italics = 0
 <
+------------------------------------------------------------------------------
+                                 *'b:org_highlight_tex'*  *'g:org_highlight_tex'*
+Value: numeric~
+Default: 1~
+
+Enable/disable syntax highlighting of inline (La)TeX blocks[4].  This option
+exists as some Org mode users don't use TeX and may find the highlighting
+annoying.
+
+To disable for all Org mode files place the following line in your vimrc:
+>
+    let g:org_highlight_tex = 0
+<
+To disable only in a single buffer, use this instead:
+>
+    let b:org_highlight_tex = 0
+<
+------------------------------------------------------------------------------
+          *'b:org_list_alphabetical_bullets'* *'g:org_list_alphabetical_bullets'*
+Value: numeric~
+Default: 0~
+
+Enable/disable alphabetical bullets on ordered lists.  This is disabled by
+default like in Emacs.
+
+To enable for all Org mode files place the following line in your vimrc:
+>
+    let g:org_list_alphabetical_bullets = 1
+<
+To enable only in a single buffer, use this instead:
+>
+    let b:org_list_alphabetical_bullets = 1
+<
 ==============================================================================
  4. CHANGE LOG                                                  *org-changelog*
 
+v1.5 [2021-03-11]~
+
+  * Added support for alphabetical ordered list bullets.  (Thanks Isti115!)
+  * Option to disable (La)TeX highlighting.  (See: |g:org_highlight_tex|)
+  * Doc update.
+
+v1.4 [2020-08-24]~
+
+  * Render "strikethrough" text as "struck through".
+  * Added syntax cluster groups for headings and hyperlinks.
+  * Made spacing consistent throughout syntax files.
+  * Minor wording tweaks to README.
+
 v1.3 [2020-05-02]~
 
   * Added syntax highlighting of LaTeX math fragments.  (Thanks Gavinok!)
@@ -165,13 +212,6 @@ v1.0 [2019-09-28]~
 ==============================================================================
  5. LEGAL                                                           *org-legal*
 
-Org.vim is based on the work of many other people (far too many to list here),
-without them org.vim would not have been possible.  The most notable of thse
-works are:
-
-  * GNU Emacs' Outline mode [1].
-  * Carsten Dominik's Org mode [2].
-
 Org.vim is distributed under the same terms as Vim itself.
 
 Copyright (c) 2018–2020, Alex Vear.
@@ -180,12 +220,20 @@ A copy of the full licence text should have been provided with this extension
 in the `LICENCE` file.  The license can also be viewed on the web [3] or by
 viewing the |license| section of the |uganda.txt| help doc from within Vim.
 
+Org.vim is based on the work of many other people (far too many to list here),
+without them org.vim would not have been possible.  The most notable of thse
+works are:
+
+  * GNU Emacs' Outline mode [1].
+  * Carsten Dominik's Org mode [2].
+
 ==============================================================================
  7. REFERENCES                                                 *org-references*
 
 [1]: <https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html>
 [2]: <https://orgmode.org/>
 [3]: <http://vimdoc.sourceforge.net/htmldoc/uganda.html#license>
+[4]: <https://orgmode.org/manual/LaTeX-fragments.html>
 
 ------------------------------------------------------------------------------
 vim:et:ts=4:sts=4:sw=4:tw=78:ft=help:norl:

syntax/org.vim

@@ -17,11 +17,12 @@ endif
 " Enable spell check for non syntax highlighted text
 syntax spell toplevel
 
+
 " Bold, underine, italic, etc.
 syntax region orgItalic        matchgroup=orgItalicDelimiter        start="\(^\|[- '"({\]]\)\@<=\/\ze[^ ]" end="^\@!\/\([^\k\/]\|$\)\@=" keepend contains=@Spell
 syntax region orgBold          matchgroup=orgBoldDelimiter          start="\(^\|[- '"({\]]\)\@<=\*\ze[^ ]" end="^\@!\*\([^\k\*]\|$\)\@=" keepend contains=@Spell
 syntax region orgUnderline     matchgroup=orgUnderlineDelimiter     start="\(^\|[- '"({\]]\)\@<=_\ze[^ ]"  end="^\@!_\([^\k_]\|$\)\@="   keepend contains=@Spell
-syntax region orgStrikethrough matchgroup=orgStrikethroughDelimiter start="\(^\|[- '"({\]]\)\@<=+\ze[^ ]"  end="^\@!+\([^\k+]\|$\)\@="   keepend contains=@Spell
+syntax region orgStrikethrough matchgroup=orgStrikethroughDelimiter start="\(^\|[ '"({\]]\)\@<=+\ze[^ ]"   end="^\@!+\([^\k+]\|$\)\@="   keepend contains=@Spell
 
 if org#option('org_use_italics', 1)
     highlight def orgItalic term=italic cterm=italic gui=italic
@@ -31,16 +32,15 @@ endif
 
 highlight def orgBold term=bold cterm=bold gui=bold
 highlight def orgUnderline term=underline cterm=underline gui=underline
-highlight def link orgBoldDelimiter      orgBold
+highlight def orgStrikethrough term=strikethrough cterm=strikethrough gui=strikethrough
+highlight def link orgBoldDelimiter orgBold
 highlight def link orgUnderlineDelimiter orgUnderline
-
-highlight def link orgStrikethrough Ignore
 highlight def link orgStrikethroughDelimiter orgStrikethrough
 
+
 " Options
 syntax match  orgOption /^\s*#+\w\+.*$/ keepend
 syntax region orgTitle matchgroup=orgOption start="\c^\s*#+TITLE:\s*" end="$" keepend oneline
-
 highlight def link orgBlockDelimiter SpecialComment
 highlight def link orgOption SpecialComment
 highlight def link orgTitle Title
@@ -74,6 +74,8 @@ syntax match orgHeading4 /^\s*\*\{4}\s\+.*$/ keepend contains=@Spell,orgTag,orgT
 syntax match orgHeading5 /^\s*\*\{5}\s\+.*$/ keepend contains=@Spell,orgTag,orgTodo,orgMath
 syntax match orgHeading6 /^\s*\*\{6,}\s\+.*$/ keepend contains=@Spell,orgTag,orgTodo,orgMath
 
+syntax cluster orgHeadingGroup contains=orgHeading1,orgHeading2,orgHeading3,orgHeading4,orgHeading5,orgHeading6
+
 syntax match orgTag /:\w\{-}:/ contained contains=orgTag
 exec 'syntax keyword orgTodo contained ' . join(org#option('org_state_keywords', ['TODO', 'NEXT', 'DONE']), ' ')
 
@@ -90,6 +92,9 @@ highlight def link orgTag Type
 " Lists
 syntax match orgUnorderedListMarker "^\s*[-+]\s\+" keepend contains=@Spell
 syntax match orgOrderedListMarker "^\s*\d\+[.)]\s\+" keepend contains=@Spell
+if org#option('org_list_alphabetical_bullets', 0)
+    syntax match orgOrderedListMarker "^\s*\a[.)]\s\+" keepend contains=@Spell
+endif
 highlight def link orgUnorderedListMarker Statement
 highlight def link orgOrderedListMarker orgUnorderedListMarker
 
@@ -107,29 +112,30 @@ syntax match orgHyperLeft /\[\{2}/ contained conceal
 syntax match orgHyperRight /\]\{2}/ contained conceal
 syntax match orgHyperURL /[^][]\{-1,}\]\[/ contains=orgHyperCentre contained conceal
 syntax match orgHyperCentre /\]\[/ contained conceal
+
+syntax cluster orgHyperlinkBracketsGroup contains=orgHyperLeft,orgHyperRight,orgHyperCentre
+syntax cluster orgHyperlinkGroup contains=orgHyperlink,orgHyperURL,orgHyperlinkBracketsGroup
+
 highlight def link orgHyperlink Underlined
 highlight def link orgHyperURL String
 highlight def link orgHyperCentre Comment
 highlight def link orgHyperLeft Comment
 highlight def link orgHyperRight Comment
 
+
 " TeX
-" Support for both inline and block based embedded latex
+"   Ref: https://orgmode.org/manual/LaTeX-fragments.html
-" eg: $Latex$ for inline or $$ LaTeX $$ for a block
+if org#option('org_highlight_tex', 1)
-" Note:
+    syntax include @LATEX syntax/tex.vim
-" - $LaTeX$ uses the tex.vim syntax for its conceal properties
+    syntax region orgMath start="\\begin\[.*\]{.*}"  end="\\end{.*}"         keepend contains=@LATEX
-" - Inspired by https://github.com/vim-pandoc/vim-pandoc-syntax
+    syntax region orgMath start="\\begin{.*}"        end="\\end{.*}"         keepend contains=@LATEX
-" - the conceal settings follows your g:tex_conceal setting for
+    syntax region orgMath start="\\\["               end="\\\]"              keepend contains=@LATEX
-"   more info run :h tex-conceal.
+    syntax region orgMath start="\\("                end="\\)"               keepend contains=@LATEX
-" Ref: https://orgmode.org/manual/LaTeX-fragments.html#LaTeX-fragments
+    syntax region orgMath start="\S\@<=\$\|\$\S\@="  end="\S\@<=\$\|\$\S\@=" keepend oneline contains=@LATEX
-syntax include @LATEX syntax/tex.vim
+    syntax region orgMath start=/\$\$/               end=/\$\$/              keepend contains=@LATEX
-syntax region orgMath     start="\\begin\[.*\]{.*}"  end="\\end{.*}"         keepend contains=@LATEX
+    syntax match  orgMath /\\\$/ conceal cchar=$
-syntax region orgMath     start="\\begin{.*}"        end="\\end{.*}"         keepend contains=@LATEX
+    highlight def link orgMath String
-syntax region orgMath     start="\\\["               end="\\\]"              keepend contains=@LATEX
+endif
-syntax region orgMath     start="\\("                end="\\)"               keepend contains=@LATEX
+
-syntax region orgMath     start="\S\@<=\$\|\$\S\@="  end="\S\@<=\$\|\$\S\@=" keepend oneline contains=@LATEX
-syntax region orgMath     start=/\$\$/               end=/\$\$/              keepend contains=@LATEX
-syntax match  orgMath /\\\$/ conceal cchar=$
-hi def link orgMath     String
 
 let b:current_syntax = 'org'

syntax/outline.vim

@@ -17,6 +17,7 @@ endif
 " Enable spell check for non syntax highlighted text
 syntax spell toplevel
 
+
 " Headings
 syntax match outlineHeading1 /^\s*\*\{1}\s\+.*$/ keepend contains=@Spell
 syntax match outlineHeading2 /^\s*\*\{2}\s\+.*$/ keepend contains=@Spell
@@ -25,6 +26,8 @@ syntax match outlineHeading4 /^\s*\*\{4}\s\+.*$/ keepend contains=@Spell
 syntax match outlineHeading5 /^\s*\*\{5}\s\+.*$/ keepend contains=@Spell
 syntax match outlineHeading6 /^\s*\*\{6,}\s\+.*$/ keepend contains=@Spell
 
+syntax cluster outlineHeadingGroup contains=outlineHeading1,outlineHeading2,outlineHeading3,outlineHeading4,outlineHeading5,outlineHeading6
+
 hi def link outlineHeading1 Title
 hi def link outlineHeading2 outlineHeading1
 hi def link outlineHeading3 outlineHeading2
@@ -32,4 +35,5 @@ hi def link outlineHeading4 outlineHeading3
 hi def link outlineHeading5 outlineHeading4
 hi def link outlineHeading6 outlineHeading5
 
+
 let b:current_syntax = 'outline'