ft-tiddlywiki-plugin.txt

*ft-tiddlywiki-plugin.txt*	Filetype plugin for TiddlyWiki wikitext markup
David Nebauer              *tiddlywiki-filetype-plugin* *ft-tiddlywiki-plugin*

==============================================================================
CONTENTS                                       *ft-tiddlywiki-plugin-contents*
  1. Introduction.................................|ft-tiddlywiki-plugin-intro|
  2. Configuration...............................|ft-tiddlywiki-plugin-config|
  3. Commands..................................|ft-tiddlywiki-plugin-commands|
  4. Features..................................|ft-tiddlywiki-plugin-features|
  5. Syntax......................................|ft-tiddlywiki-plugin-syntax|
  6. Mappings..................................|ft-tiddlywiki-plugin-mappings|
  7. Autocommands..............................|ft-tiddlywiki-plugin-autocmds|
  8. Functions................................|ft-tiddlywiki-plugin-functions|

==============================================================================
INTRODUCTION                                      *ft-tiddlywiki-plugin-intro*

A filetype plugin for Tiddlywiki tiddlers.

TiddlyWiki (https://tiddlywiki.com) is a non-linear notebook, or wiki. The
basis of TiddlyWiki is capturing information into the smallest possible
semantically meaningful units, called "tiddlers", and aggregating them in
meaningful ways to present narrative stories.

From version 5 of TiddlyWiki each tiddler is stored in its own file, which has
a "tid" extension. While there are a variety of types of tiddler serving
different functions, this plugin supports the basic content type of tiddler,
consisting of metadata followed by content. The metadata is a series of
key:value pairs, one to a line. The content is a flavour of wikitext markup
developed for TiddlyWiki (https://tiddlywiki.com/#WikiText).

==============================================================================
CONFIGURATION                                    *ft-tiddlywiki-plugin-config*

                                                        *b:disable_tiddlywiki*
Prevents ft-tiddlywiki-plugin loading if set to a true value before it would
normally load.

                                                      *g:default_tiddler_tags*
Default tag names to be added when converting a "tid" file to a "div.tiddler"
file. Tag names specified in tiddler metadata are added to these tag names.
For more details see the |:TWTidToTiddler| command and
|tiddlywiki#convertTidToDivTiddler()| function.

                                                   *g:default_tiddler_creator*
Default creator name to be added when converting a "tid" file to a
"div.tiddler" file. Any creator name specified in tiddler metadata overrides
the tag name set in this variable. For more details see the |:TWTidToTiddler|
command and |tiddlywiki#convertTidToDivTiddler()| function.

                                                     *g:tiddlywiki_autoupdate*
If this variable is set to a true value, automatic updating of the tiddler's
modification time is enabled. For more information see the
|tiddlywiki#updateModTime()| function and |ft-tiddlywiki-plugin-autocmds|
section.

                                                        *g:no_tiddlywiki_maps*
Prevents loading of plugin mappings if set to a true value. (See also
discussion of "g:no_plugin_maps" in |ft-tiddlywiki-plugin-mappings|.)

==============================================================================
COMMANDS                                       *ft-tiddlywiki-plugin-commands*

:[N]TWAddCanonicalUri [root] [images]                     *:TWAddCanonicalUri*
  Calls |tiddlywiki#addCanonicalUri()| to select an external image and add a
  corresponding "_canonical_uri" metadata field to the top of the tiddler (or
  replace an existing one). The wiki [root] directory is provided as an
  absolute path while the [images] subdirectory is relative to the wiki root
  directory, under which it must be located. The user is able to manually
  select either or both directory manually if not specified in the command
  call.

  When specifying the directories on the command line the easiest method is to
  use directory completion to enter the absolute images directory path, and
  then add spacing just after the wiki root directory. In that way the first
  argument becomes the wiki root directory and the second argument becomes the
  images directory path relative to the wiki root directory. Take particular
  care when the directory paths themselves contain spaces.

:[N]TWConvertTidToDivTiddler [field]               *:TWConvertTidToDivTiddler*
  Calls |tiddlywiki#convertTidToDivTiddler()| to convert a "tid" style file to
  a "div.tiddler" style file and then open it. Accepts optional metadata
  [field] names as arguments.

:[N]TWInitialiseTiddler                                 *:TWInitialiseTiddler*
  Calls |tiddlywiki#initialiseTiddler()| to insert metadata fields "created",
  "modified", "tags", "title" and "type" at the head of the file.

:[N]TWTiddlify [field]                                           *:TWTiddlify*
  Calls |tiddlywiki#tiddlify()| to convert a file to a "tid" tiddler file.
  Accepts optional metadata [field] names as arguments.

:[N]TWUniquifyDataTiddler                             *:TWUniquifyDataTiddler*
  Calls |tiddlywiki#uniquefyDataTiddler()| to add a unique numeric prefix to
  each line (row) of a dictionary data tiddler. Each line gets the prefix
  "X: " where "X" is an incrementing integer starting at 1 on the first line.

:[N]TWUpdateModificationTime                       *:TWUpdateModificationTime*
  Calls |tiddlywiki#updateModTime()| to update the timestamp in the "modified"
  metadata field.

==============================================================================
FEATURES                                       *ft-tiddlywiki-plugin-features*

ft-tiddlywiki-plugin defines the "tiddlywiki" filetype and provides
|ft-tiddlywiki-plugin-syntax| highlighting, some useful
|ft-tiddlywiki-plugin-functions|, |ft-tiddlywiki-plugin-mappings|,
|ft-tiddlywiki-plugin-commands| and optional |ft-tiddlywiki-plugin-autocmds|
assist with tiddler metadata.

==============================================================================
SYNTAX                                           *ft-tiddlywiki-plugin-syntax*

ft-tiddlywiki-plugin defines the filetype "tiddlywiki" for TiddlyWiki's
flavour of wikitext markup. This filetype is automatically assigned to files
with a ".tid" extension.

==============================================================================
MAPPINGS                                       *ft-tiddlywiki-plugin-mappings*

The following mappings are provided for |Normal-mode|:

<Leader>ti
  * initialise tiddler file
  * calls |tiddlywiki#initialiseTiddler()|

<Leader>tm
  * update modification timestamp
  * calls |tiddlywiki#updateModTime()|

ft-tiddlywiki-plugin adheres to the convention that plugin mappings are not
loaded if either of the variables "g:no_plugin_maps" or |g:no_tiddlywiki_maps|
is set to a true value.

==============================================================================
AUTOCOMMANDS                                   *ft-tiddlywiki-plugin-autocmds*

ft-tiddlywiki-plugin can be configured to automatically update the tiddler's
modification time (in the metadata "modified" field) when the file is changed
and saved. While disabled by default, it can be enabled with the
|g:tiddlywiki_autoupdate| variable.

The autocmd responsible for this behaviour can be found in the "tiddlywiki"
autocmd group (see |autocmd-groups|) and can be viewed (see |autocmd-list|).

==============================================================================
FUNCTIONS                                     *ft-tiddlywiki-plugin-functions*

tiddlywiki#addCanonicalUri([root], [images])    *tiddlywiki#addCanonicalUri()*
  Adds or replaces the metadata line in which the "_canonical_uri" field is
  defined. This field is used when images are stored in a subdirectory of the
  wiki root directory, traditionally "wikiroot/images", and external image
  tiddlers are used to refer to them.

  The user can provide the wiki [root] directory and [images] directory, or
  select them manually. The images directory has to be located under the wiki
  root directory, and if specified as a parameter only the portion relative to
  the wiki root directory is given. For example, if the wiki root directory is
  "~/wiki" and the full path to the images directory is
  "~/wiki/output/images", then the images parameter would be given as
  "output/images".

  The user selects an image file from the images directory and a corresponding
  metadata line for the canonical uri is inserted at the top of the file, or
  overwrites an existing canonical uri.

  An inserted metadata field line may look like:
>
      _canonical_uri: images/My Image.png
<

tiddlywiki#convertTidToDivTiddler([field])
                                         *tiddlywiki#convertTidToDivTiddler()*
  Converts the contents of the current buffer, assumed to be in the syle of a
  "tid" file, to the style of a "div.tiddler" file, writes the "div.tiddler"
  file to the current directory and opens it in a new buffer. The "tid" and
  "div.tiddler" file styles are described in the "TiddlerFiles" tiddler at
  https://tiddlywiki.com.)

  If the current buffer is associated with a file the output "div.tiddler"
  file is given the same base name. If the current buffer is not associated
  with a file the user is prompted to enter one. The output file is given a
  "tiddler" extension.

  The "tid" content is assumed to be structured with at least one metadata
  line at the top of the document separated from the tiddler content/text by a
  blank line. Each metadata lines looks like "field: description". The content
  of the tags field is space-separated tag names; tag names containing spaces
  should be enclosed by doubled square brackets, e.g., "[[tag name]]". Default
  tag names set using the |g:default_tiddler_tags| setting are added to any
  tag names defined in tiddler metadata. A default creator name can be set
  using |g:default_tiddler_creator|, but this is overridden by a creator set
  in tiddler metadata. If, for some reason, the same field is defined multiple
  times in metadata, the following occurs:
    * for the "tags" field, all field values are concatenated
    * for other fields, the last field value overrides all others.

  There is an optional pre-processing step in which lines at the top of the
  file can have field names prepended to them. This is triggered by passing
  [field] names to the function as arguments. Consider, for example, the
  function invocation:
>
      call tiddlywiki#convertTidToDivTiddler('title', 'tags')
<
  This results in "title: " being prepended to the first line in the file and
  "tags: " being prepended to the second line in the file. If a blank line
  occurs before the field name arguments are exhausted, remaining field names
  are ignored.

  Because each field value becomes a html attribute value, some characters can
  confuse tiddlywiki's import parser. These characters include double-quotes,
  less-than signs and greater-than signs, which for that reason are silently
  replaced with single quotes, full width less-than signs (unicode code point
  FF1C) and full-width greater-than signs (unicode code point FF1E),
  respectively, during conversion.
  Throws ERROR(CantEdit) if unable to open tiddler file for editing
  Throws ERROR(NoCreated) if unable to set created date
  Throws ERROR(DeleteFail) if error occurs during file deletion
  Throws ERROR(NoBoundary) if no metadata/content boundary located
  Throws ERROR(NoContent) if no content/text in tiddler
  Throws ERROR(NoFilename) if no output filename entered by user
  Throws ERROR(NoModified) if unable to set modified date
  Throws ERROR(WriteFail) if error occurs during file write

tiddlywiki#initialiseTiddler()                *tiddlywiki#initialiseTiddler()*
  Insert metadata fields at start of file. More specifically, the following
  metadata fields are inserted:
    * "created: <TIME>"
    * "modified: <TIME>"
    * "tags: "
    * "title: "
    * "type: text/vnd.tiddlywiki"
  followed by an empty line. "<TIME>" is the current time in tiddlywiki
  format.

tiddlywiki#tiddlify([field])                           *tiddlywiki#tiddlify()*
  Converts the contents of the current buffer to a basic tiddler. The first
  cluster of lines (up to the first empty line) are assumed to be metadata
  lines.

  Each metadata lines looks like "field: description". The content of the tags
  field is space-separated tag names; tag names containing spaces should be
  enclosed by doubled square brackets, e.g., "[[tag name]]".  Default tag
  names set using the |g:default_tiddler_tags| setting are added to any tag
  names defined in tiddler metadata. A default creator name can be set using
  |g:default_tiddler_creator|, but this is overridden by a creator set in
  tiddler metadata. If, for some reason, the same field is defined multiple
  times in metadata, the following occurs:
    * for the "tags" field, all field values are concatenated
    * for other fields, the last field value overrides all others.

  There is an optional pre-processing step in which lines at the top of the
  file can have field names prepended to them. This is triggered by passing
  [field] names to the function as arguments. Consider, for example, the
  function invocation:
>
      call tiddlywiki#tiddlify('title', 'tags')
<
  This results in "title: " being prepended to the first line in the file and
  "tags: " being prepended to the second line in the file. If a blank line
  occurs before the field name arguments are exhausted, remaining field names
  are ignored.
  Throws ERROR(NoCreated) if unable to set created date
  Throws ERROR(NoBoundary) if no metadata/content boundary located
  Throws ERROR(NoModified) if unable to set modified date

tiddlywiki#uniquefyDataTiddler()            *tiddlywiki#uniquefyDataTiddler()*
  Adds a unique numeric prefix to rows in a dictionary data tiddler. More
  specifically, it adds "X: " to the beginning of each row where "X" is an
  incrementing integer starting at 1 on the first line.

  Executes the following vimscript commands:
>
    execute 'let n=[0]'
    execute "%s/^/\\=map(n, 'v:val+1')[0] . ': '/"
<
  which are the equivalent of the following command executed in
  |Cmdline-mode|:
>
    let n=[0] | %s/^/\=map(n, 'v:val+1')[0] . ': '/
<
  Throws ERROR(CantUniquify) if unable to complete prefix insertion

tiddlywiki#updateModTime()                        *tiddlywiki#updateModTime()*
  Updates the "modified" metadata field with the current time.
  Throws ERROR(NoModified) if unable to locate "modified" metadata field
  Throws ERROR(CantModify) if unable to modify "modified" metadata field
  Throws ERROR(CantSetPos) if unable to restore original cursor position
  Throws ERROR(NoDate) if unable to obtain system date


vim:tw=78:ts=8:ft=help:norl: