[comment {--- punk::docgen generated from inline doctools comments ---}]
[comment {--- punk::docgen DO NOT EDIT DOCS HERE UNLESS YOU REMOVE THESE COMMENT LINES ---}]
[comment {--- punk::docgen overwrites this file ---}]
[manpage_begin fauxlink_module_fauxlink 0 0.1.1]
[copyright "2024"]
[titledesc {faux link application shortcuts}]  [comment {-- Name section and table of contents description --}]
[moddesc {.fauxlink .fxlnk}]             [comment {-- Description at end of page heading --}]
[require fauxlink]
[keywords symlink faux fake shortcut toml]
[description]
[para] A cross platform shortcut/symlink alternative.
[para] Unapologetically ugly - but practical in certain circumstances.
[para] A solution is required for application-driven filesystem links that survives cross platform moves as well as
[para] archiving and packaging systems.
[para] The target is specified in a minimally-encoded form in the filename itself - but still human readable.
[para] format of name <nominalname>#<encodedtarget>.fauxlink
[para] where <nominalname> can be empty - then the effective nominal name is the tail of the <encodedtarget>
[para] The file extension must be .fauxlink or .fxlnk
[para] The + symbol substitutes for forward-slashes.
[para] Other chars can be encoded using url-like encoding - (but only up to %7E !)
[para] We deliberately treat higher % sequences literally.
[para] This means actual uri::urn encoded unicode sequences (e.g %E2%99%A5 [lb]heart[rb]) can remain literal for linking to urls.
[para] e.g if an actual + or # is required in a filename or path segment they can be encoded as %2B & %23
[para] e.g a link to a file file#A.txt in parent dir could be:
[para] file%23A.txt#..+file%23A.txt.fauxlink
[para] or equivalently (but obviously affecting sorting) #..+file%23A.txt.fauxlink
[para] The <nominalname> can be unrelated to the actual target
[para] e.g datafile.dat#..+file%23A.txt.fauxlink
[para] This system has no filesystem support - and must be completely application driven.
[para] This can be useful for example in application test packages which may be tarred or zipped and moved cross platform.
[para] The target being fully specified in the name means the file doesn't have to be read for the target to be determined
[para] Extensions to behaviour should be added in the file as text data in Toml format,
[para] with custom data being under a single application-chosen table name
[para] The toplevel Toml table [lb]fauxlink[rb] is reserved for core extensions to this system.
[para] Aside from the 2 used for delimiting (+ #)
[para] certain characters which might normally be allowed in filesystems are required to be encoded
[para] e.g space and tab are required to be %20 %09
[para] Others that require encoding are: * ? \ / | : ; " < >
[para] The nul character in raw form, when detected, is always mapped away to the empty string - as very few filesystems support it.
[para] Control characters and other punctuation is optional to encode.
[para] Generally utf-8 should be used where possible and unicode characters can often be left unencoded on modern systems.
[para] Where encoding of unicode is desired in the nominalname,encodedtarget,tag or comment portions it can be specified as %UXXXXXXXX
[para] There must be between 1 and 8 X digits following the %U. Interpretation of chars following %U stops at the first non-hex character.
[para] This means %Utest would not get any translation as there were no hex digits so it would come out as %Utest

 ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
[section Overview]
[para] overview of fauxlink
[subsection Concepts]
[para] -
[subsection dependencies]
[para] packages used by fauxlink
[list_begin itemized]
[item] [package {Tcl 8.6-}]
[list_end]
[section API]
[subsection {Namespace fauxlink::class}]
[para] class definitions
[list_begin enumerated]
[list_end] [comment {--- end class enumeration ---}]
[subsection {Namespace fauxlink}]
[para] Core API functions for fauxlink
[list_begin definitions]
[list_end] [comment {--- end definitions namespace fauxlink ---}]
[subsection {Namespace fauxlink::lib}]
[para] Secondary functions that are part of the API
[list_begin definitions]
[list_end] [comment {--- end definitions namespace fauxlink::lib ---}]
[section Internal]
[subsection {Namespace fauxlink::system}]
[para] Internal functions that are not part of the API
[manpage_end]