README

   1 swg -- simple wiki/zettelkästen helper/generator.
   2
   3 Here is suggested trivially simple format of plaintext data, ready to be
   4 used for zettelkästen, wiki, static website, info documentation generation.
   5
   6 There are various already existing similar solutions. But most of them
   7 are either too complex, or not too flexible enough, or far from being
   8 human friendly, or can not be adequately viewed by plain text pagers.
   9
  10 => https://en.wikipedia.org/wiki/Plain_Old_Documentation Plain Old Documentation, POD\r
  11 => https://docutils.sourceforge.io/rst.html reStructured Text (reST)\r
  12 => https://www.sphinx-doc.org/en/master/ Sphinx\r
  13 => https://en.wikipedia.org/wiki/Docbook DocBook\r
  14 => https://asciidoc-py.github.io/index.html AsciiDoc\r
  15 => https://vimwiki.github.io/ Vimwiki\r
  16 => https://www.latex-project.org/ LaTeX\r
  17 => https://man.openbsd.org/mdoc.7 mdoc\r
  18 => https://troff.org/ troff\r
  19 => https://en.wikipedia.org/wiki/HTML HTML\r
  20 => https://geminiprotocol.net/docs/gemtext.gmi gemtext\r
  21 => https://daringfireball.net/projects/markdown/ Markdown\r
  22 => https://commonmark.org/ CommonMark\r
  23 => https://www.gnu.org/software/texinfo/ GNU Texinfo + Info\r
  24
  25 Texinfo seems to be the best choice in most cases. It is official
  26 documentation format in GNU operating system. But it has only single
  27 implementation, not so low learning curve and necessity of additional
  28 tools at least for viewing .info files conveniently. It can be an
  29 overkill for small projects or people fearing of any markup language.
  30
  31 Could it be simpler? What could we need except for ordinary bunch of
  32 plaintext files in directory hierarchy? We still want ability to do
  33 conversion to HTML, which has a variety of hyperlink-capable browsers.
  34
  35 * Need of internal pages linking.
  36   This is necessity for either wiki or zettelkästen like use cases.
  37 * Ability to insert arbitrary links (URI/URL).
  38 * Ability to insert links to images.
  39 * Ability to track internal linking and be able to generate list of
  40   backlinks. That is necessity for zettelkästen use case. That also can
  41   be used for creating indices (automatically generated pages with a
  42   list of backlinks).
  43
  44 Actually that is all! The only crucial thing is ability to specify and
  45 determine internal links and be able to track them between the pages.
  46 That is the main task that utility was written. HTML generation is
  47 completely optional feature.
  48
  49 Look how [LINKS] should be made. How [FORMAT] is defined.
  50 How your [VIM] editor can be used with all of that.
  51 Look for [USAGE] of swg utility itself.
  52
  53 Use grep, git-grep or similar tools to search through pages.
  54 fzf can be used to quickly navigate to necessary page/file.
  55 recoll can be used to index and search through the whole data.
  56 => https://github.com/junegunn/fzf fzf\r
  57 => https://www.lesbonscomptes.com/recoll/ recoll\r