Write change log for version 1.3 of org.vim

"LaTeX math fragments" will now be syntax highlighted in Org mode files.
If `conceallevel=2` is set, the LaTeX symbols will be displayed as their
Unicode equivalents.  E.g.

    $\alpha$ --> α
    \( x^2 \)  --> x²

For more info, see: <https://orgmode.org/manual/LaTeX-fragments.html#LaTeX-fragments>

.gitattributes

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

README.org

@@ -1,7 +1,9 @@
 #+TITLE: Org mode and Outline mode syntax highlighting for Vim
 
-Org.vim is a very minimal [[https://orgmode.org][Org mode]] and [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html][Outline mode]] plugin for
+Org.vim is a very minimal [[https://orgmode.org][Org mode]] and
-[[https://www.vim.org][Vim]] providing only syntax highlighting and folding.
+[[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
@@ -12,9 +14,35 @@ 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.
 
-*Notice*: this project is considered complete by the author. You can still
+*Note*: this project is considered /feature complete/ by the author, so the
-report bugs and request additional features, however it is unlikely that new
+addition of new features will be unlikely.
-features will be added.
+
+
+** Installation
+
+Installation of Org.vim can be performed by using your preferred plugin/package
+management tool(s).  If you don't have a Vim package manager I recommend using
+Vim 8 packages.
+
+Just run these 2 commands from your shell.
+
+#+BEGIN_SRC sh
+git clone https://github.com/axvr/org.vim ~/.vim/pack/plugins/start/org
+vim +'helptags ~/.vim/pack/plugins/start/org/doc/' +q
+#+END_SRC
+
+Once installed check out the Org.vim manual (run ~:help org.txt~ to open it) for
+usage information and configuration options.
+
+
+** Screenshots
+
+Different Vim colour schemes will result in different appearances.
+
+| [[https://github.com/romainl/Apprentice][Apprentice]] | [[https://github.com/axvr/photon.vim][Photon]] |
+|--------+------------|
+| [[https://raw.githubusercontent.com/axvr/org.vim/images/apprentice.png]] | [[https://raw.githubusercontent.com/axvr/org.vim/images/photon.png]] |
+
 
 ** Licence
 

TODO

@@ -1,11 +1,12 @@
 MAYBE:
-  - Better link syntax highlighting (more similar to links in vim-markdown)
+  - Syntax highlight checkboxes and checkbox cookies
-  - Syntax highlight bullets and checkboxes
+  - Separate syntax group for heading delimiters
-  - Different syntax group for heading delimiters
+  - 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:
-  - Add working links
-    - Maybe utilise Vim-Waikiki and override default Vim mappings
-    - Open man pages (use ':h :Man')
-    - Add 'org-store-link' and 'org-insert-link' implementations
   - Implement Emacs's abbreviations (e.g. '\<s<TAB>')

doc/org.txt

@@ -7,12 +7,11 @@
 Welcome to the org.vim user manual.            *org*  *org.vim*  *vim-org*  *outline*
 
     1. Introduction ............................... |org-intro|
-    2. Installation ............................... |org-install|
+    2. Usage ...................................... |org-usage|
-    3. Basic syntax ............................... |org-syntax|
+    3. Configuration .............................. |org-configuration|
-    4. Configuration .............................. |org-configuration|
+    4. Change log ................................. |org-changelog|
-    5. Change log ................................. |org-changelog|
+    5. Legal ...................................... |org-legal|
-    6. Legal ...................................... |org-legal|
+    6. References ................................. |org-references|
-    7. References ................................. |org-references|
 
 ==============================================================================
  1. INTRODUCTION                                                    *org-intro*
@@ -25,87 +24,21 @@ Org mode (and Outline mode) files, rather than trying to be a full featured
 Org mode plugin -- that is what Emacs is for.
 
 ==============================================================================
- 2. INSTALLATION                                                  *org-install*
+ 2. USAGE                                                           *org-usage*
-
-Installation of Org.vim can be performed by using your favourite Vim
-plugin/package management tool(s).
-
-==============================================================================
- 3. BASIC SYNTAX                                                   *org-syntax*
-
-Outline mode isn't used much anymore, one place it is still used is for GNU
-Emacs release notes.  It contains only a single piece of syntax: heading
-levels denoted by asterisks.
->
-    * This is a heading
-
-    The first heading is equivalent to <h1> tags in HTML files.
-
-    ** This is a sub-heading
-
-    This heading uses 2 asterisks to denote that it is a below the previous
-    heading.
-
-    *** This is a sub-sub-heading
-
-    * This is another top level heading
-
-    Org.vim supports as many heading levels as you want, and each of these
-    headings can use Vim's folding keys and fold navigation.
-<
-Org mode is a huge superset of Outline mode.  It uses the same heading syntax
-mentioned above, but supports many, many more features.  Org.vim supports the
-core subset of Org mode syntax, which should be suitable for most use cases.
-
-The following is a short overview of essential Org mode syntax.
->
-    Org mode supports *bold*, /italic/, _underline_ and +strikethrough+ text
-    which is delimited by asterisks, forward-slashes, underscores, and pluses
-    respectively.
-
-    Paragraphs are separated by empty lines.
-
-    ~monospaced~ and =verbatim= text are delimited by equals signs and tilde
-    respectively.
-
-    : Entire lines can be marked as verbatim by prepending with a colon.
-
-    # Comments are lines prepended with a hash.
-
-    This is a link to the Org.vim repository [[https://github.com/axvr/org.vim]]
-
-    This is also a link to the [[https://github.com/axvr/org.vim][Org.vim repository]]
-    where the text "Org.vim repository" is the title of the link (link text).
-
-    - This is an item in a list.
-    - This is another item in the same list.
-      - This is a sub-item for the above list item.
-        - This is a sub-item for the previous list item.
-    + List items can also be denoted by using a plus sign
-    1. Or by numbering each item.
-    2. Like so.
-      - [ ] List items can also have checkboxes by using open and closing
-            square brackets.
-      - [X] By placing an uppercase X in between the square brackets you can
-            mark the item as "done".
-<
-Org.vim supports a lot more of Org mode's vast syntax than was mentioned here.
-You can learn much more of Org mode's syntax online.
 
 When Org.vim is installed, files ending with the extension `.org` will
-automatically have syntax highlighting and folding support enabled.  It can
+automatically have syntax highlighting and folding support enabled.  You can
-also be manually enabled with the following command.
+also manually enable it by setting the 'filetype' option.
 >
     :set filetype=org
 <
 Outline mode doesn't have a file extension like Org mode so you will have to
-enable it manually.  This is simply done by opening the file and runing the
+enable it manually.
-following command.
 >
     :set filetype=outline
 <
 ==============================================================================
- 4. CONFIGURATION                                           *org-configuration*
+ 3. CONFIGURATION                                           *org-configuration*
 
                                                                   *org-folding*
 
@@ -123,6 +56,23 @@ Or if you want folding enabled and all folds opened by default, use
 <
 For more information on folding in Vim, refer to |fold.txt|.
 
+------------------------------------------------------------------------------
+                                                            *org-conceal-links*
+
+You can tell Vim to conceal links by using the built-in 'conceallevel' and
+'concealcursor' options.
+
+For example, you can make Vim collapse an Org mode link to look like it would
+within Emacs or a Web browser (i.e. only showing the link title).
+>
+    [[https://www.vim.org][Vim website]] --> Vim website
+<
+This is achieved with this |autocmd|:
+>
+    autocmd FileType org setlocal conceallevel=2 concealcursor=nc
+<
+Note: long concealed text can act weird when "hard-wraping" text in Vim.
+
 ------------------------------------------------------------------------------
                                *'b:org_state_keywords'*  *'g:org_state_keywords'*
 Value: list of strings~
@@ -138,35 +88,6 @@ Note: state keywords are case sensitive.
 State keywords can be set on specific buffers by using |'b:org_state_keywords'|
 rather than |'g:org_state_keywords'|.
 
-------------------------------------------------------------------------------
-                                 *'b:org_conceal_links'*  *'g:org_conceal_links'*
-Value: numeric~
-Default: 1~
-
-This option changes how Org mode links are rendered.  If this option is
-enabled, most of the link syntax will be collapsed to look as it would within
-Emacs or a web browser; only showing the (underlined) link text.
->
-    [[https://www.vim.org][Vim website]] --> Vim website
-<
-When in insert mode with the cursor on that line, Vim will show the full link
-syntax.  This feature is enabled by default, however the way Vim treats
-concealed text can be annoying, so it can be disabled.
-
-To disable for all Org mode files, place the following line in your vimrc:
->
-    let g:org_conceal_links = 0
-<
-To disable for a specific file use this instead:
->
-    let b:org_conceal_links = 0
-<
-If you would like to modify how links are concealed, you can disable this
-option, and manually set the |conceallevel| and |concealcursor| options from
-an |autocmd| like so.
->
-    autocmd FileType org setlocal conceallevel=2 concealcursor=nc
-<
 ------------------------------------------------------------------------------
                                      *'b:org_clean_folds'*  *'g:org_clean_folds'*
 Value: numeric~
@@ -207,12 +128,31 @@ To disable italics only in a single buffer, use this instead:
     let b:org_use_italics = 0
 <
 ==============================================================================
- 5. CHANGE LOG                                                  *org-changelog*
+ 4. CHANGE LOG                                                  *org-changelog*
+
+v1.3 [2020-05-02]~
+
+  * Added syntax highlighting of LaTeX math fragments.  (Thanks Gavinok!)
+  * Improved detection of inline bold, italic, underline, strike through,
+    verbatim and code syntax.
+  * Grey out "strike through" text by default.
+  * Updated README content and added screenshots.
+  * Removed the "basic Org mode syntax" section from this document.
+
+v1.2 [2020-02-15]~
+
+  * Improved syntax highlighting of links and turned off link concealing.
+    * Added |org_conceal_links| doc section on how turn on link concealing.
+  * Syntax highlight list item bullets and numbers.
+    * Make Vim correctly format lists without messing up indentation.
+  * Allow lower case in option keys and dynamic block markers.
+  * Remove a couple of unnecessary 'fillchars' rules.
+  * Minor README content update.
 
 v1.1 [2020-01-05]~
 
   * Added documentation on folding configuration (|org-folding|).
-  * Added |'g:org_clean_folds'| option.
+  * Added 'g:org_clean_folds' option.
   * Improved accuracy of in-line delimiter matching.
   * Various minor documentation fixes.
   * Rewrote README in Org mode.
@@ -223,7 +163,7 @@ v1.0 [2019-09-28]~
   * Initial stable release.
 
 ==============================================================================
- 6. LEGAL                                                           *org-legal*
+ 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

ftplugin/org.vim

@@ -11,6 +11,9 @@
 "   Web: <https://orgmode.org/manual/index.html>
 
 setlocal commentstring=#%s
+setlocal comments=fb:*,fb:-,fb:+,b:#,b:\:
+setlocal formatoptions+=ncqlt
+let &l:formatlistpat = '^\s*\(\d\+[.)]\|[+-]\)\s\+'
 
 setlocal foldexpr=org#fold_expr()
 setlocal foldmethod=expr
@@ -18,11 +21,4 @@ setlocal foldmethod=expr
 if org#option('org_clean_folds', 0)
     setlocal foldtext=org#fold_text()
     setlocal fillchars-=fold:-
-    setlocal fillchars-=fold:\
-endif
-
-" Conceal Org mode link syntax
-if org#option('org_conceal_links', 1)
-    setlocal conceallevel=2
-    setlocal concealcursor=nc
 endif

ftplugin/outline.vim

@@ -16,5 +16,4 @@ setlocal foldmethod=expr
 if org#option('org_clean_folds', 0)
     setlocal foldtext=org#fold_text()
     setlocal fillchars-=fold:-
-    setlocal fillchars-=fold:\
 endif

syntax/org.vim

@@ -18,10 +18,10 @@ endif
 syntax spell toplevel
 
 " Bold, underine, italic, etc.
-syntax region orgItalic        matchgroup=orgItalicDelimiter        start="[^ \t\k]\@<!\/\k\@=\/\@!" end="\k\@<=\/\@<!\/" keepend contains=@Spell
+syntax region orgItalic        matchgroup=orgItalicDelimiter        start="\(^\|[- '"({\]]\)\@<=\/\ze[^ ]" end="^\@!\/\([^\k\/]\|$\)\@=" keepend contains=@Spell
-syntax region orgBold          matchgroup=orgBoldDelimiter          start="[^ \t\k]\@<!\*\k\@=\*\@!" end="\k\@<=\*\@<!\*" keepend contains=@Spell
+syntax region orgBold          matchgroup=orgBoldDelimiter          start="\(^\|[- '"({\]]\)\@<=\*\ze[^ ]" end="^\@!\*\([^\k\*]\|$\)\@=" keepend contains=@Spell
-syntax region orgUnderline     matchgroup=orgUnderlineDelimiter     start="[^ \t\k]\@<!_\k\@=_\@!"   end="\k\@<=_\@<!_"   keepend contains=@Spell
+syntax region orgUnderline     matchgroup=orgUnderlineDelimiter     start="\(^\|[- '"({\]]\)\@<=_\ze[^ ]"  end="^\@!_\([^\k_]\|$\)\@="   keepend contains=@Spell
-syntax region orgStrikethrough matchgroup=orgStrikethroughDelimiter start="[^ \t\k]\@<!+\k\@=+\@!"   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
@@ -34,10 +34,12 @@ highlight def orgUnderline term=underline cterm=underline gui=underline
 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="^\s*#+TITLE:\s*" end="$" keepend oneline
+syntax region orgTitle matchgroup=orgOption start="\c^\s*#+TITLE:\s*" end="$" keepend oneline
 
 highlight def link orgBlockDelimiter SpecialComment
 highlight def link orgOption SpecialComment
@@ -45,12 +47,12 @@ highlight def link orgTitle Title
 
 
 " Code and vervatim text
-syntax region orgCode     matchgroup=orgCodeDelimiter     start="[^ \t\k]\@<!\~\k\@=\~\@!" end="\k\@<=\~\@<!\~" keepend
+syntax region orgCode     matchgroup=orgCodeDelimiter     start="\(^\|[- '"({\]]\)\@<=\~\ze[^ ]" end="^\@!\~\([^\k\~]\|$\)\@=" keepend
-syntax region orgVerbatim matchgroup=orgVerbatimDelimiter start="[^ \t\k]\@<!=\k\@==\@!"   end="\k\@<==\@<!="   keepend
+syntax region orgVerbatim matchgroup=orgVerbatimDelimiter start="\(^\|[- '"({\]]\)\@<==\ze[^ ]"  end="^\@!=\([^\k=]\|$\)\@="   keepend
 syntax match  orgVerbatim /^\s*: .*$/ keepend
-syntax region orgVerbatim matchgroup=orgBlockDelimiter start="^\s*#+BEGIN_.*"      end="^\s*#+END_.*"      keepend
+syntax region orgVerbatim matchgroup=orgBlockDelimiter start="\c^\s*#+BEGIN_.*"      end="\c^\s*#+END_.*"      keepend
-syntax region orgCode     matchgroup=orgBlockDelimiter start="^\s*#+BEGIN_SRC"     end="^\s*#+END_SRC"     keepend
+syntax region orgCode     matchgroup=orgBlockDelimiter start="\c^\s*#+BEGIN_SRC"     end="\c^\s*#+END_SRC"     keepend
-syntax region orgCode     matchgroup=orgBlockDelimiter start="^\s*#+BEGIN_EXAMPLE" end="^\s*#+END_EXAMPLE" keepend
+syntax region orgCode     matchgroup=orgBlockDelimiter start="\c^\s*#+BEGIN_EXAMPLE" end="\c^\s*#+END_EXAMPLE" keepend
 
 highlight def link orgVerbatim Identifier
 highlight def link orgVerbatimDelimiter orgVerbatim
@@ -60,17 +62,17 @@ highlight def link orgCodeDelimiter orgCode
 
 " Comments
 syntax match  orgComment /^\s*#\s\+.*$/ keepend
-syntax region orgComment matchgroup=orgBlockDelimiter start="^\s*#+BEGIN_COMMENT" end="^\s*#+END_COMMENT" keepend
+syntax region orgComment matchgroup=orgBlockDelimiter start="\c^\s*#+BEGIN_COMMENT" end="\c^\s*#+END_COMMENT" keepend
 highlight def link orgComment Comment
 
 
 " Headings
-syntax match orgHeading1 /^\s*\*\{1}\s\+.*$/ keepend contains=@Spell,orgTag,orgTodo
+syntax match orgHeading1 /^\s*\*\{1}\s\+.*$/ keepend contains=@Spell,orgTag,orgTodo,orgMath
-syntax match orgHeading2 /^\s*\*\{2}\s\+.*$/ keepend contains=@Spell,orgTag,orgTodo
+syntax match orgHeading2 /^\s*\*\{2}\s\+.*$/ keepend contains=@Spell,orgTag,orgTodo,orgMath
-syntax match orgHeading3 /^\s*\*\{3}\s\+.*$/ keepend contains=@Spell,orgTag,orgTodo
+syntax match orgHeading3 /^\s*\*\{3}\s\+.*$/ keepend contains=@Spell,orgTag,orgTodo,orgMath
-syntax match orgHeading4 /^\s*\*\{4}\s\+.*$/ keepend contains=@Spell,orgTag,orgTodo
+syntax match orgHeading4 /^\s*\*\{4}\s\+.*$/ keepend contains=@Spell,orgTag,orgTodo,orgMath
-syntax match orgHeading5 /^\s*\*\{5}\s\+.*$/ keepend contains=@Spell,orgTag,orgTodo
+syntax match orgHeading5 /^\s*\*\{5}\s\+.*$/ keepend contains=@Spell,orgTag,orgTodo,orgMath
-syntax match orgHeading6 /^\s*\*\{6,}\s\+.*$/ keepend contains=@Spell,orgTag,orgTodo
+syntax match orgHeading6 /^\s*\*\{6,}\s\+.*$/ keepend contains=@Spell,orgTag,orgTodo,orgMath
 
 syntax match orgTag /:\w\{-}:/ contained contains=orgTag
 exec 'syntax keyword orgTodo contained ' . join(org#option('org_state_keywords', ['TODO', 'NEXT', 'DONE']), ' ')
@@ -85,6 +87,13 @@ highlight def link orgTodo Todo
 highlight def link orgTag Type
 
 
+" Lists
+syntax match orgUnorderedListMarker "^\s*[-+]\s\+" keepend contains=@Spell
+syntax match orgOrderedListMarker "^\s*\d\+[.)]\s\+" keepend contains=@Spell
+highlight def link orgUnorderedListMarker Statement
+highlight def link orgOrderedListMarker orgUnorderedListMarker
+
+
 " Timestamps
 syntax match orgTimestampActive /<\d\{4}-\d\{2}-\d\{2}.\{-}>/ keepend
 syntax match orgTimestampInactive /\[\d\{4}-\d\{2}-\d\{2}.\{-}\]/ keepend
@@ -96,8 +105,31 @@ highlight def link orgTimestampInactive Comment
 syntax match orgHyperlink /\[\{2}\([^][]\{-1,}\]\[\)\?[^][]\{-1,}\]\{2}/ containedin=ALL contains=orgHyperLeft,orgHyperRight,orgHyperURL
 syntax match orgHyperLeft /\[\{2}/ contained conceal
 syntax match orgHyperRight /\]\{2}/ contained conceal
-syntax match orgHyperURL /[^][]\{-1,}\]\[/ contained conceal
+syntax match orgHyperURL /[^][]\{-1,}\]\[/ contains=orgHyperCentre contained conceal
+syntax match orgHyperCentre /\]\[/ contained conceal
 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
+" eg: $Latex$ for inline or $$ LaTeX $$ for a block
+" Note:
+" - $LaTeX$ uses the tex.vim syntax for its conceal properties
+" - Inspired by https://github.com/vim-pandoc/vim-pandoc-syntax
+" - the conceal settings follows your g:tex_conceal setting for
+"   more info run :h tex-conceal.
+" Ref: https://orgmode.org/manual/LaTeX-fragments.html#LaTeX-fragments
+syntax include @LATEX syntax/tex.vim
+syntax region orgMath     start="\\begin\[.*\]{.*}"  end="\\end{.*}"         keepend contains=@LATEX
+syntax region orgMath     start="\\begin{.*}"        end="\\end{.*}"         keepend contains=@LATEX
+syntax region orgMath     start="\\\["               end="\\\]"              keepend contains=@LATEX
+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'