--- /dev/null
+Page format is trivial: it is arbitrary formatted plaintext.
+It will be rendered in HTML through the <pre> tag.
+The only specific inline formatting construction is [LINKS].
+
+But there are also special "command" lines, ending with "\r\n"
+instead of ordinary "\n". Here are possible commands, playing
+role only (currently) during HTML generation.
+
+* => URL[ optional text]
+ Creates <a href="URL">{optional text|URL}</a> link in HTML.
+* img URL[ optional text]
+ Creates <img src="URL" [alt="optional text"] /> in HTML.
+* raw ...
+ Just inserts ... line to HTML output as-is.
+* # ...
+ Does nothing, commented line.
+* do-links
+ Forcefully creates a table with all links on the page.
+* do-backs
+ Forcefully creates a table with all backlinks to the page.
+* include [page]
+ Include contents of the specified page. Brackets here are
+ for making a link to page.
--- /dev/null
+(internal) Links are placed in square brackets. They must not contain
+whitespaces or word-splitting characters, to be friendly to editor's
+"goto file" feature. CamelCase or kebab-case are perfect!
+
+Pages can be placed in directory hierarchy. Path to page is relative to
+the root of the project. $root/foo/bar file can be linked from any page
+with the [foo/bar] link. Link to the directory (category) itself,
+containing "index" file (may be autogenerated), must contain trailing /.
+Relative links are not allowed.
--- /dev/null
+zk -- zettelkästen/wiki/static website helper/generator.
+
+Here is suggested trivially simple format of plaintext data, ready to be
+used for zettelkästen, wiki, static website, documentation generation.
+
+There are various already existing similar solutions. But most of them
+are either too complex, or not too flexible enough, or far from being
+human friendly, or can not be adequately viewed by plain text pagers.
+
+=> https://en.wikipedia.org/wiki/Plain_Old_Documentation Plain Old Documentation, POD\r
+=> https://docutils.sourceforge.io/rst.html, reStructured Text (reST)\r
+=> https://www.sphinx-doc.org/en/master/ Sphinx\r
+=> https://en.wikipedia.org/wiki/Docbook DocBook\r
+=> https://asciidoc-py.github.io/index.html AsciiDoc\r
+=> https://vimwiki.github.io/ Vimwiki\r
+=> https://www.latex-project.org/ LaTeX\r
+=> https://man.openbsd.org/mdoc.7 mdoc\r
+=> https://troff.org/ troff\r
+=> https://en.wikipedia.org/wiki/HTML HTML\r
+=> https://geminiprotocol.net/docs/gemtext.gmi gemtext\r
+=> https://daringfireball.net/projects/markdown/ Markdown\r
+=> https://commonmark.org/ CommonMark\r
+=> https://www.gnu.org/software/texinfo/ GNU Texinfo + Info\r
+
+Texinfo seems to be the best choice in most cases. It is official
+documentation format in GNU operating system. But it has only single
+implementation, not so low learning curve and necessity of additional
+tools at least for viewing .info files conveniently. It can be an
+overkill for small projects or people fearing of any markup language.
+
+Could it be simpler? What could we need except for ordinary bunch of
+plaintext files in directory hierarchy? We still want ability to do
+conversion to HTML, which has a variety of hyperlink-capable browsers.
+
+* Need of internal pages linking.
+ This is necessity for either wiki or zettelkästen like use cases.
+* Ability to insert arbitrary links (URI/URL).
+* Ability to insert links to images.
+* Ability to track internal linking and be able to generate list of
+ backlinks. That is necessity for zettelkästen use case. That also can
+ be used for creating indices (automatically generated pages with a
+ list of backlinks).
+
+Actually that is all! The only crucial thing is ability to specify and
+determine internal links and be able to track them between the pages.
+That is the main task that utility was written. HTML generation is
+completely optional feature.
+
+Look how [LINKS] should be made. How [FORMAT] is defined.
+How your [VIM] editor can be used with all of that.
+Look for [USAGE] of zk utility itself.
+
+Use grep, git-grep or similar tools to search through pages.
+fzf can be used to quickly navigate to necessary page/file.
+recoll can be used to index and search through the whole data.
+=> https://github.com/junegunn/fzf fzf\r
+=> https://www.lesbonscomptes.com/recoll/ recoll\r
--- /dev/null
+* zk links path/to/page
+ Prints all (internal) links presented on the page.
+* zk back path/to/page
+ Prints all (internal) backlinks to the page.
+* zk htmls path/to/dir
+ Rendered the current directory to a bunch of HTMLS.
+* zk dot | dot -Tpng >relations.png
+ Generates Graphviz'es dot graph with internal links relationships.
+
+If directory does not have "index" file, then it will be autogenerated
+with all files in the directory (category) and all backlinks to it.
+
+If $ZK_DO_LINKS=0 environment variable is set, then no links table will
+be generated on the pages by default. $ZK_DO_BACKS=0 disables backlinks
+table generation.
+
+.zkignore may contain regular expressions (one per line) to ignore
+specified files during processing. Your directory may contain images or
+binary files, that must not be processed.
+
+If $ZK_PRINT_MISSING environment variable is set, then warning will be
+print for links leading to non-existent pages.
+
+How to forcefully change the title of the generated HTML page?
+Use sed/perl to replace "<title>..." line in it.
--- /dev/null
+Name your plaintext files without any spaces and word separators.
+That gives ability to use "goto file" ("gf") command on the word
+under the cursor. If there is "[Foo/Bar]" word under the cursor,
+then pressing "gf" will open Foo/Bar file for editing.
+
+Run editor at the root of your notes directory for being able to
+goto any page relative to the root.
+
+Use expand("%:r") to get current file path relative to the root.
+
+Square bracketed links can be highlighted with:
+
+ syntax region zkLink start="\[\S" end="\S]"
+ highlight link zkLink String
+
+Use filename completion (:help compl-filename) to complete
+directories and filenames in them.
# zk -- zettelkästen/wiki/static website helper/generator
# Copyright (C) 2022-2025 Sergey Matveev <stargrave@stargrave.org>
-=pod
-
-=encoding utf-8
-
-=head1 SYNOPSIS
-
-zk -- zettelkästen/wiki/static website helper/generator
-
-=head1 USAGE
-
-=over
-
-=item *
-
-Use plain text files. One file per note/record.
-
-=item *
-
-Use file names that are friendly to vi editor word boundary determination.
-
-=item *
-
-You can safely place that notes in subdirectories hierarchy.
-
-=item *
-
-Edit and view your notes from their root path (zettelkästen root). That
-way if you press C<gf> on F<Foo/Bar/Baz> word in Vim, then it will open
-F<Foo/Bar/Baz> file in current window.
-
-=item *
-
-Use C<expand("%:r")> function to get current file path relative to the root.
-
-=item *
-
-Place links to another notes inside square brackets.
-You can highlight them with:
-
- syntax region zkLink start="\[\S" end="\S]"
- highlight link zkLink String
-
-=item *
-
-Link to the directory's index can be made with C<[Dir/]>.
-
-=item *
-
-Use Vim's filename completion (C<:help compl-filename>) to complete
-directories and filenames in them.
-
-=item *
-
-L<fzf|https://github.com/junegunn/fzf> related tools can be used to
-navigate among existing notes.
-
-=item *
-
-Ordinary C<grep>, C<git-jump> or similar tools can be used to search and
-quickly open results in the editor.
-
-=item *
-
-C<=E<gt> URL[ optional text]\r> on a separate line will add a link to the
-specified URL (with optional text). Pay attention that line contains
-carriage-return character at the end.
-
-=item *
-
-C<img URL[ alt]\r> on a separate line will add an image with
-optional alternative text similarly as link is specified.
-
-=back
-
-The only thing Vim lacks there is ability to tell who backlinks
-to the specified page. zk can be used to show what pages backlinks to
-specified page and what pages are referenced by it:
-
- $ zk links some/page
- Another/Page
- SomePage
- $ zk backs some/page
- [...]
-
-That can be used to make categories and tags on notes. If note contains
-a link to category/tag (even an empty file), then it will be backlinked.
-
- $ zk htmls path/to/dir
-
-Will convert all your notes to HTMLs with properly created links
-to other pages. It also will include all backlinks in them. Each
-directory will also contain index page with links to all
-existing pages in current directory and to subdirectories.
-
-=head1 (BACK)LINKS GENERATION
-
-Set C<ZK_DO_LINKS=0> to disable automatic links-table creation in the
-HTML output. Set C<ZK_DO_BACKS=0> to disable automatic backlinks-table.
-If C<do-links\r> line is presented, then links-table is forcefully generated.
-C<do-backs\r> generated backlinks table.
-
-=head1 IGNORED FILES
-
-You can ignore specified files processing by placing regular expressions
-on separate lines in .zkignore file. They are applied to full relative
-path of walked files.
-
-=head1 HISTORY
-
-Older version of that script, written on Z shell, can be found in Git history.
-
-=cut
-
use strict;
use warnings;
\t$0 backs PAGE
\t$0 htmls DIR
\t$0 dot | dot -Tpng >png
+
+By default ZK_DO_LINKS=1 and ZK_DO_BACKS=1 are set.
+Do not forget about .zkignore with regular expressions.
";
exit 1;
}