File: hywiki.el.html
This is Hyperbole's markup-free personal Wiki system for note-taking
and automatic wiki word highlighting and hyperlinking. It uses Org
mode for note taking and adds automatic hyperlinking of HyWikiWords
within Org files in hywiki-directory (default = "~/hywiki"), where
a HyWikiWord is a capitalized word that contains upper and lowercase
letters only and has a corresponding HyWikiWord.org wiki page file
below hywiki-directory. HyWikiWords require no delimiters.
HyWikiWords are also recognized in text buffers after the global
minor mode, hywiki-mode is enabled via {M-x hywiki-mode RET}. To
create or jump to a HyWiki page, simply type o ut a potential
HyWikiWord or move point onto one and press the Action Key {M-RET}.
This will create the associated page if it does not exist. This
also highlights any other instances of HyWikiWords across all
visible Emacs windows. HyWiki is built for scalability and has been
tested to be performant with 10,000 HyWikiWords.
Once Hyperbole has been loaded and activated, HyWikiWords (with or
without delimiters) are automatically highlighted and active in
the following contexts:
- HyWiki page buffers;
- non-special text buffers, when hywiki-mode is enabled;
- comments and strings in programming buffers, when
hywiki-mode is enabled.
As HyWikiWords are typed, highlighting occurs after a trailing
whitespace or punctuation character is added, or when it is
surrounded by a matching pair of characters such as curly braces
or single square brackets. Since Org links use double square
brackets and Org targets use double or triple angle brackets,
HyWikiWords within these delimiters are ignored.
You can also create Org links to HyWikiWords in any non-special text
buffer by surrounding them with double square brackets and the
'hy:' prefix, as in: [[hy:MyWikiWord]]. If you set
hywiki-org-link-type-required to nil, then you don't need the
prefix, e.g. [[MyWikiWord]]; existing HyWiki page names then will
override Org's standard handling of such links. To prevent Org
mode's binding of {M-RET} from splitting lines and creating new
headlines when on a HyWikiWord whose page has not yet been
created, set hsys-org-enable-smart-keys to t so that
Hyperbole's Action Key does the right thing in this context.
HyWikiWord links can also link to a section headline within a page
by simply following the page name with a '#' character and then the
section headline name. For example, if your Emacs page has a "Major
Modes" section, then either Emacs#Major-Modes or [[hy:Emacs#Major
Modes]] will work as a link to that section. Note that without the
square bracket delimiters, you must convert spaces in section names
to '-' characters. As long as the page exists, section links are
highlighted regardless of whether associated sections exist or not.
When activating a link with a section reference, you will get an
error if the section does not exist.
By default (hywiki-mode = :pages), HyWikiWords are
auto-highlighted within HyWiki pages only. Outside of such pages,
hywiki-mode must be set to :all to enable auto-highlighting in
programming and text modes. Auto-highlighting depends on pre- and
post-command-hook settings. If an error occurs running one of
these, the associated hook is removed. To restore the
auto-highlight hooks use {C-u C-h h h m} to toggle hywiki-mode;
this also enables auto-highlighting when hywiki-mode is non-nil.
The custom setting, hypb:exclude-major-modes (default = nil), is
a list of major modes to exclude from HyWikiWord auto-highlighting
and recognition.
Within programming modes, HyWikiWords are highlighted/hyperlinked
within comments and double-quoted strings only. For programming
modes in which you want HyWikiWords recognized everywhere, add
them to the custom setting, hywiki-highlight-all-in-prog-modes
(default = '(lisp-interaction-mode)).
HyWiki adds two implicit button types to Hyperbole:
hywiki-word - create and display HyWikiWord referents;
hywiki-existing-word - display an existing HyWikiWord referent.
hywiki-word is one of the lowest priority implicit button types
so that it triggers only when other types are not recognized first.
A HyWiki can be exported to HTML for publishing to the web via Org
mode's publish a project feature. {M-x hywiki-publish-to-html RET}
will and that's it! Add a prefix argument to force regeneration of all
HyWiki pages, rather than only those that have been updated.
The full set of HyWiki-specific Org publish properties are set in
the variable hywiki-org-publish-project-alist. When the HyWiki
code is loaded into Emacs, it automatically integrates these
properties with Org's publishing framework, so when in a HyWiki
page, you can use the standard {C-c C-e P p} current project publish
command.
There are a few publishing settings you can customize prior to
loading Hyperbole's HyWiki code.
HyWiki html files are saved in:
(hywiki-org-get-publish-property :publishing-directory)
Customize this directory with:
{M-x customize-variable RET hywiki-org-publishing-directory RET}.
HyWiki html files are generated by the function given by:
(hywiki-org-get-publish-property :publishing-function)
Customize the value of this function if necessary with:
{M-x customize-variable RET hywiki-org-publishing-function RET}.
This section summarizes HyWikiWord Actions based on the
hywiki-referent-prompt-flag When nil When t
-------------------------------------------------------------------------------------
Action Key hywiki-word-create-and-display
or HyWiki/Create Create Page and Display Create Referent and Display
Assist Key hywiki-word-create-and-display
or C-u HyWiki/Create Create Referent and Display Create Page and Display
hywiki-word-create hywiki-create-page with Msg hywiki-create-referent with Msg
C-u hywiki-word-create hywiki-create-referent with Msg hywiki-create-page with Msg