Add change log and fix minor mistakes in docs

Previously the following would've caused everything after the `/` to be
italicised (until it found a second `/`).

    foo/bar

The same happened with all of the other in-line delimiters.  This was
clearly not good enough.

The new in-line delimiter matching is now much closer to Emacs' than
before while maintaining Unicode support (as well as Vim can offer).

README.md

@@ -1,31 +0,0 @@
-# Org mode and Outline mode syntax highlighting for Vim
-
-Org.vim is a very minimal [Org mode][] and [Outline mode][] plugin for
-[Vim](https://www.vim.org) providing only syntax highlighting and folding.
-
-This plugin aims to replicate Vim's [existing Markdown](https://github.com/tpope/vim-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.
-
-Originally created so I would be able to quickly edit and easily read Org mode
-files in Vim without any of _the bells and whistles_ of the original Emacs
-implementation.  It also allowed me use [Orgzly](https://github.com/orgzly/orgzly-android/)
-(highly recommended) without worrying about Emacs lock-in.
-
-**Notice**: this project is considered complete by the author. You can still
-report bugs and request additional features, however it is unlikely that new
-features will be added.
-
-## Licence
-
-Copyright (c) 2018-2019, Alex Vear.
-
-Org.vim is distributed under the same terms as Vim itself.
-
-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](http://vimdoc.sourceforge.net/htmldoc/uganda.html#license) or by invoking
-`:help license` from within Vim.
-
-[Outline mode]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html
-[Org mode]: https://orgmode.org

README.org

@@ -0,0 +1,28 @@
+#+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
+[[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.
+
+Originally created so I would be able to quickly edit and easily read Org mode
+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
+report bugs and request additional features, however it is unlikely that new
+features will be added.
+
+** Licence
+
+Copyright (c) 2018–2020, Alex Vear.
+
+Org.vim is distributed under the same terms as Vim itself.
+
+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
+[[http://vimdoc.sourceforge.net/htmldoc/uganda.html#license][web]] or by invoking
+~:help license~ from within Vim.

TODO

@@ -1,9 +1,7 @@
 MAYBE:
   - Better link syntax highlighting (more similar to links in vim-markdown)
   - Syntax highlight bullets and checkboxes
-  - Option to enable/disable folding (similar to g:markdown_folding)
   - Different syntax group for heading delimiters
-  - Change log in Vim doc
 
 UNLIKELY:
   - Add working links

autoload/org.vim

@@ -4,9 +4,23 @@
 " License:      Vim (see `:help license`)
 " Location:     autoload/org.vim
 " Website:      https://github.com/axvr/org.vim
-" Last Change:  2019-09-22
+" Last Change:  2020-01-04
 
 " Fallback chain for options. Buffer local --> Global --> default.
-function org#option(name, default)
+function org#option(name, default) abort
     return get(b:, a:name, get(g:, a:name, a:default))
 endfunction
+
+" Emacs-like fold text.
+function org#fold_text() abort
+    return getline(v:foldstart) . '...'
+endfunction
+
+" Check fold depth of a line.
+function org#fold_expr()
+    let l:depth = match(getline(v:lnum), '\(^\*\+\)\@<=\( .*$\)\@=')
+    if l:depth > 0 && synIDattr(synID(v:lnum, 1, 1), 'name') =~# '\m^o\(rg\|utline\)Heading'
+        return ">" . l:depth
+    endif
+    return "="
+endfunction

doc/org.txt

@@ -10,8 +10,9 @@ Welcome to the org.vim user manual.            *org*  *org.vim*  *vim-org*  *out
     2. Installation ............................... |org-install|
     3. Basic syntax ............................... |org-syntax|
     4. Configuration .............................. |org-configuration|
-    5. Legal ...................................... |org-legal|
+    5. Change log ................................. |org-changelog|
-    6. References ................................. |org-references|
+    6. Legal ...................................... |org-legal|
+    7. References ................................. |org-references|
 
 ==============================================================================
  1. INTRODUCTION                                                    *org-intro*
@@ -52,7 +53,7 @@ levels denoted by asterisks.
     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
+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.
 
@@ -64,7 +65,7 @@ The following is a short overview of essential Org mode syntax.
 
     Paragraphs are separated by empty lines.
 
-    =monospaced= and ~verbatim~ text are delimited by equals signs and tilde
+    ~monospaced~ and =verbatim= text are delimited by equals signs and tilde
     respectively.
 
     : Entire lines can be marked as verbatim by prepending with a colon.
@@ -98,7 +99,7 @@ also be manually enabled with the following command.
     :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.  This is simply done by opening the file and runing the
 following command.
 >
     :set filetype=outline
@@ -106,6 +107,23 @@ following command.
 ==============================================================================
  4. CONFIGURATION                                           *org-configuration*
 
+                                                                  *org-folding*
+
+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'.
+>
+    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|.
+
+------------------------------------------------------------------------------
                                *'b:org_state_keywords'*  *'g:org_state_keywords'*
 Value: list of strings~
 Default: ['TODO', 'NEXT', 'DONE']~
@@ -129,7 +147,7 @@ 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
+    [[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
@@ -150,27 +168,62 @@ an |autocmd| like so.
     autocmd FileType org setlocal conceallevel=2 concealcursor=nc
 <
 ------------------------------------------------------------------------------
-                                     *'b:org_use_italics'*  *'g:org_use_italics'*
+                                     *'b:org_clean_folds'*  *'g:org_clean_folds'*
 Value: numeric~
 Default: 0~
 
-Display italic org-mode markup (e.g. `/this is italic org-mode markup/`) using
+Vim's default styling for folds is quite ugly.  Enabling this option will
+remove much of the visual noise and suffix the folded heading text with an
+ellipsis (`...`) making folds look the same as they do in Emacs' Org mode (and
+Outline mode).
+>
+    * Heading 1...
+<
+This option can be enabled for all buffers like so:
+>
+    let g:org_clean_folds = 1
+<
+Alternatively it can be enabled for specific buffers:
+>
+    let b:org_clean_folds = 1
+<
+------------------------------------------------------------------------------
+                                     *'b:org_use_italics'*  *'g:org_use_italics'*
+Value: numeric~
+Default: 1~
+
+Display italic Org mode markup (e.g. `/this is italic Org mode markup/`) using
 the italic variant of your font.
 
-Note: this option is disabled by default because some terminals and monospaced
+As some terminals, terminal multiplexers and monospaced fonts don't support
-fonts don't support the use of italics.
+the use of italics, org.vim provides a mechanism to disable italic text.
 
-To enable this feature in all Org mode files place the following line in your
+To disable for all Org mode files place the following line in your vimrc:
-vimrc:
 >
-    let g:org_use_italics = 1
+    let g:org_use_italics = 0
 <
-To enable italics only in a single buffer, use this instead:
+To disable italics only in a single buffer, use this instead:
 >
-    let b:org_use_italics = 1
+    let b:org_use_italics = 0
 <
 ==============================================================================
- 5. LEGAL                                                           *org-legal*
+ 5. CHANGE LOG                                                  *org-changelog*
+
+v1.1 [2020-01-05]~
+
+  * Added documentation on folding configuration (|org-folding|).
+  * Added |'g:org_clean_folds'| option.
+  * Improved accuracy of in-line delimiter matching.
+  * Various minor documentation fixes.
+  * Rewrote README in Org mode.
+  * Enabled rendering of italics by default.
+
+v1.0 [2019-09-28]~
+
+  * Initial stable release.
+
+==============================================================================
+ 6. 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
@@ -181,14 +234,14 @@ works are:
 
 Org.vim is distributed under the same terms as Vim itself.
 
-Copyright (c) 2018-2019, Alex Vear.
+Copyright (c) 2018–2020, Alex Vear.
 
 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.
 
 ==============================================================================
- 6. REFERENCES                                                 *org-references*
+ 7. REFERENCES                                                 *org-references*
 
 [1]: <https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html>
 [2]: <https://orgmode.org/>

ftplugin/org.vim

@@ -4,7 +4,7 @@
 " License:      Vim (see `:help license`)
 " Location:     ftplugin/org.vim
 " Website:      https://github.com/axvr/org.vim
-" Last Change:  2019-09-22
+" Last Change:  2020-01-04
 "
 " Reference Specification: Org mode manual
 "   GNU Info: `$ info Org`
@@ -12,17 +12,15 @@
 
 setlocal commentstring=#%s
 
-function! OrgFold()
+setlocal foldexpr=org#fold_expr()
-    let l:depth = match(getline(v:lnum), '\(^\*\+\)\@<=\( .*$\)\@=')
-    if l:depth > 0 && synIDattr(synID(v:lnum, 1, 1), 'name') =~# 'orgHeading'
-        return ">" . l:depth
-    endif
-    return "="
-endfunction
-
-setlocal foldexpr=OrgFold()
 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

ftplugin/outline.vim

@@ -4,19 +4,17 @@
 " License:      Vim (see `:help license`)
 " Location:     ftplugin/outline.vim
 " Website:      https://github.com/axvr/org.vim
-" Last Change:  2019-09-22
+" Last Change:  2020-01-04
 "
 " Reference Specification: GNU Emacs Manual, section 'Outline Mode'
 "   GNU Info: `$ info Emacs Outline Mode`
 "   Web: <https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html>
 
-function! OutlineFold()
+setlocal foldexpr=org#fold_expr()
-    let l:depth = match(getline(v:lnum), '\(^\*\+\)\@<=\( .*$\)\@=')
-    if l:depth > 0 && synIDattr(synID(v:lnum, 1, 1), 'name') =~# 'outlineHeading'
-        return ">" . l:depth
-    endif
-    return "="
-endfunction
-
-setlocal foldexpr=OutlineFold()
 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

@@ -4,7 +4,7 @@
 " License:      Vim (see `:help license`)
 " Location:     syntax/org.vim
 " Website:      https://github.com/axvr/org.vim
-" Last Change:  2019-09-28
+" Last Change:  2020-01-05
 "
 " Reference Specification: Org mode manual
 "   GNU Info: `$ info Org`
@@ -18,12 +18,12 @@ endif
 syntax spell toplevel
 
 " Bold, underine, italic, etc.
-syntax region orgItalic        matchgroup=orgItalicDelimiter        start="\/\S\@=\/\@!" end="\S\@<=\/\@<!\/" keepend contains=@Spell
+syntax region orgItalic        matchgroup=orgItalicDelimiter        start="[^ \t\k]\@<!\/\k\@=\/\@!" end="\k\@<=\/\@<!\/" keepend contains=@Spell
-syntax region orgBold          matchgroup=orgBoldDelimiter          start="\*\S\@=\*\@!" end="\S\@<=\*\@<!\*" keepend contains=@Spell
+syntax region orgBold          matchgroup=orgBoldDelimiter          start="[^ \t\k]\@<!\*\k\@=\*\@!" end="\k\@<=\*\@<!\*" keepend contains=@Spell
-syntax region orgUnderline     matchgroup=orgUnderlineDelimiter     start="_\S\@=_\@!"   end="\S\@<=_\@<!_"   keepend contains=@Spell
+syntax region orgUnderline     matchgroup=orgUnderlineDelimiter     start="[^ \t\k]\@<!_\k\@=_\@!"   end="\k\@<=_\@<!_"   keepend contains=@Spell
-syntax region orgStrikethrough matchgroup=orgStrikethroughDelimiter start="+\S\@=+\@!"   end="\S\@<=+\@<!+"   keepend contains=@Spell
+syntax region orgStrikethrough matchgroup=orgStrikethroughDelimiter start="[^ \t\k]\@<!+\k\@=+\@!"   end="\k\@<=+\@<!+"   keepend contains=@Spell
 
-if org#option('org_use_italics', 0)
+if org#option('org_use_italics', 1)
     highlight def orgItalic term=italic cterm=italic gui=italic
 else
     highlight def orgItalic term=none cterm=none gui=none
@@ -31,7 +31,6 @@ endif
 
 highlight def orgBold term=bold cterm=bold gui=bold
 highlight def orgUnderline term=underline cterm=underline gui=underline
-highlight def link orgItalicDelimiter    orgItalic
 highlight def link orgBoldDelimiter      orgBold
 highlight def link orgUnderlineDelimiter orgUnderline
 
@@ -46,8 +45,8 @@ highlight def link orgTitle Title
 
 
 " Code and vervatim text
-syntax region orgCode     matchgroup=orgCodeDelimiter     start="=\S\@==\@!" end="\S\@<==\@<!=" keepend
+syntax region orgCode     matchgroup=orgCodeDelimiter     start="[^ \t\k]\@<!\~\k\@=\~\@!" end="\k\@<=\~\@<!\~" keepend
-syntax region orgVerbatim matchgroup=orgVerbatimDelimiter start="\~\S\@=\~\@!" end="\S\@<=\~\@<!\~" keepend
+syntax region orgVerbatim matchgroup=orgVerbatimDelimiter start="[^ \t\k]\@<!=\k\@==\@!"   end="\k\@<==\@<!="   keepend
 syntax match  orgVerbatim /^\s*: .*$/ keepend
 syntax region orgVerbatim matchgroup=orgBlockDelimiter start="^\s*#+BEGIN_.*"      end="^\s*#+END_.*"      keepend
 syntax region orgCode     matchgroup=orgBlockDelimiter start="^\s*#+BEGIN_SRC"     end="^\s*#+END_SRC"     keepend