You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
72 lines
4.3 KiB
72 lines
4.3 KiB
[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]
|
|
|