The entities.list file, in the zim share directory /usr/share/zim contains the full list of supported entity types (like \copy etc).
Created Friday 11/05/2007
This is the staring point for personal installation notes, configurationm example scripts, tips and documentation relating specifically to Linux. Configuration, shell and script examples are specific to GNU Linux and have a propensity to Fedora Core. Differences between Fedora versions are indicated where possible but an attempt is made to keep the documentation in line with the current release.
This section is not really an index of the Linux wiki but some of the more important topics covered in this wiki are:
The Zim files are plain text files that use textile markup. Textile is a basic wiki-like syntax is simple enough that the contents of the files can be read in a plain text editor, such as vim. Textile is simple and is summarised as:
The entities.list file, in the zim share directory /usr/share/zim contains the full list of supported entity types (like \copy etc).
Zim namepaces can be organized hierarchically so that [[foo]] is (relative) reference to a wiki context in the current namespace. This reference is equivelant to [[:foo]]. A sub-namespace such as [[:foo:bar]] defines wiki content for a file named bar.txt in the namespace foo (i.e., a directory called foo).
Note: Both [[foo]] and [[:foo]] refer to the same content
Zim supports an interwiki-like syntax, which allows wiki words to refer to external wikis. The zim installation comes with pre-configured with a bunch of interwiki refs, such as Wikipedia (wp), amazon (amazon), RFC (rfc), Split Brain Wiki (doku) and etc. The Zim Interwiki url configuration is defined in the urls.list file in the zim library directory, which is typically /usr/share/zim/urls.list. See also #5, man page refs as well, which is another form of interwiki syntax.
Note: The file urls.list in /usr/share/zim lists the supported interwiki grammar. This list can be extended via the local zim config (see doco on XDG Base Directory in Zim help)
Zim provides heaps of shortcuts such as Interwiki, mailto, image, multimedia and more. One of the more unique aspects to Zim is the ability to quickly reference local man page content. This can be done with syntax such as man?ls which is translated into a namespace ref for the section 1 man page the ls command. Here is the man page for ls(1). Presentation of a man page reference is the same as the reference itself. E.g., man?ls this can be changed to ls(1) by editing the markup to [[man?ls|ls(1)]].
Note: Zim's Man.pm is located under the vendor_perl pathname for perl5 (e.g., /usr/lib/perl5/vendor_perl/5.10.0/Zim/Store)
Zim opens a link that it identifies as a man page link via detecting the link type (as man) and then redirecting link execution through Man.pm. The implementation of Man.pm sends a --version option to man(1) on the O/S and uses the result to determine if man is installed. However, the current implementation (upto and including 0.28) directs stderr to /dev/null and passes the result back to the caller. A non-null result indicates that man is installed and Zim launches a dialog with the man page content. This does not work in Fedora as man's versioning information (from the --version option) is actually directed to stderr. In addition, the version info also includes a blank line. A solution is to do both of:
A patch(1) encapsulating the above changes is:
--- Man.pm 2009-07-23 13:19:17.000000000 +1000
+++ Man.pm__fix_for_FCLinux 2009-07-23 13:39:17.000000000 +1000
@@ -180,7 +180,16 @@
sub open_man {
my $fh;
+# foonix fix for man on FC Linux: When executing man(1) with the '--version' option, nFC Linux man
+# spits out version info to stderr and includes a blank line. The original zim command throws out
+# stderr and so the resulting 'version' output will be empty, which zim then uses to mean "hey, there's
+# no man(1) binary installed here" and so fails to load the man page (even though we've been directed
+# here by page links like 'man?ls(1)'
+
+ #OLD zim: open $fh, "man @_ 2> $null |" or return undef;
open $fh, "man @_ 2>&1 | sed '/^\$/d' |" or return undef;
+ # no binmode :utf8 here because man output can contain invalid chars
+ # instead we use the eval Encode option per line in get_parse_tree
return $fh;
}
Warning: The man?name shortcut does not export well to (e.g.,) html
The man-page short cut (man?name) is useful within the Zim environment, as Zim is able to tranlate the grammar into a request to display the local man page. A problem occurs when a Zim page in textile format is exported to (e.g.,) html. Most of the textile markup references are fine as they are simply assembled into href tags. Any existing http:// references in the markup are also translated into hrefs. However, for man page refs, the translation to href is not particularly useful as the value of the tag for something like man?ls is <a href="ls">man?ls</a>, which is an invalid reference.
An approach for exporting the Zim textile markup is to translate man page short-cuts to hrefs which redirect to online man page content, as provided e.g., by linux.die.net. For example, ls(1), the ls content in section 1 content the man pages, could translate (for linux.die.net) to http://linux.die.net/man/1/ls. For other sections, simply subsitute the relevant section number, e.g., http://linux.die.net/man/8/mount for section 8 of the manual. Alternatively, phpunixman provides a query interface that could be exploited for the same result. E.g., http://phpunixman.sourceforge.net/index.php?parameter=mount&mode=man§ion=8
Stuart Moorfoot © 11 May 2007 foo@bund.com.au