diff options
| author | Lorry Tar Creator <lorry-tar-importer@baserock.org> | 2008-09-01 18:44:56 +0000 |
|---|---|---|
| committer | <> | 2013-07-02 12:44:56 +0000 |
| commit | bd4e1730fe4d7878c4e5e2c13ea489f59e7e0f27 (patch) | |
| tree | 5e605cc37a7e484e7008c7934f61e2cd25a0d57b /docs | |
| download | rarian-master.tar.gz | |
Imported from /home/lorry/working-area/delta_rarian/rarian-0.8.1.tar.bz2.HEADrarian-0.8.1master
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile.am | 9 | ||||
| -rw-r--r-- | docs/Makefile.in | 390 | ||||
| -rw-r--r-- | docs/help-spec-0.2.xml | 839 | ||||
| -rw-r--r-- | docs/index.xhtml | 39 | ||||
| -rw-r--r-- | docs/omf_equivalence.txt | 244 | ||||
| -rw-r--r-- | docs/rar-lib.xhtml | 360 | ||||
| -rw-r--r-- | docs/rar-mdf.xhtml | 160 | ||||
| -rw-r--r-- | docs/rar-skcompat.xhtml | 147 | ||||
| -rw-r--r-- | docs/rarian.document.in | 8 |
9 files changed, 2196 insertions, 0 deletions
diff --git a/docs/Makefile.am b/docs/Makefile.am new file mode 100644 index 0000000..0b3236e --- /dev/null +++ b/docs/Makefile.am @@ -0,0 +1,9 @@ +EXTRA_DIST = help-spec-0.2.xml index.xhtml rar-mdf.xhtml rar-lib.xhtml rar-skcompat.xhtml rarian.document.in omf_equivalence.txt + +manualdir = $(datadir)/librarian/manual + +manual_DATA = help-spec-0.2.xml index.xhtml rar-mdf.xhtml rar-lib.xhtml rar-skcompat.xhtml + +metadatadir = $(datadir)/help + +metadata_DATA = rarian.document
\ No newline at end of file diff --git a/docs/Makefile.in b/docs/Makefile.in new file mode 100644 index 0000000..122ef43 --- /dev/null +++ b/docs/Makefile.in @@ -0,0 +1,390 @@ +# Makefile.in generated by automake 1.10.1 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = docs +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in \ + $(srcdir)/rarian.document.in +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = rarian.document +SOURCES = +DIST_SOURCES = +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = `echo $$p | sed -e 's|^.*/||'`; +am__installdirs = "$(DESTDIR)$(manualdir)" "$(DESTDIR)$(metadatadir)" +manualDATA_INSTALL = $(INSTALL_DATA) +metadataDATA_INSTALL = $(INSTALL_DATA) +DATA = $(manual_DATA) $(metadata_DATA) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AR = @AR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +BASH = @BASH@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CONVERT_DIR = @CONVERT_DIR@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CXX = @CXX@ +CXXCPP = @CXXCPP@ +CXXDEPMODE = @CXXDEPMODE@ +CXXFLAGS = @CXXFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DISTCHECK_CONFIGURE_FLAGS = @DISTCHECK_CONFIGURE_FLAGS@ +DSYMUTIL = @DSYMUTIL@ +ECHO = @ECHO@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +ENABLE_INSTALL = @ENABLE_INSTALL@ +ENABLE_OMF_READ = @ENABLE_OMF_READ@ +ENABLE_SKDB_UPDATE = @ENABLE_SKDB_UPDATE@ +ENABLE_SK_COMPAT = @ENABLE_SK_COMPAT@ +EXEEXT = @EXEEXT@ +F77 = @F77@ +FFLAGS = @FFLAGS@ +GREP = @GREP@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MKDIR_P = @MKDIR_P@ +NMEDIT = @NMEDIT@ +OBJEXT = @OBJEXT@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +RANLIB = @RANLIB@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +VERSION = @VERSION@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +ac_ct_F77 = @ac_ct_F77@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +have_bash = @have_bash@ +have_xslt = @have_xslt@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +EXTRA_DIST = help-spec-0.2.xml index.xhtml rar-mdf.xhtml rar-lib.xhtml rar-skcompat.xhtml rarian.document.in omf_equivalence.txt +manualdir = $(datadir)/librarian/manual +manual_DATA = help-spec-0.2.xml index.xhtml rar-mdf.xhtml rar-lib.xhtml rar-skcompat.xhtml +metadatadir = $(datadir)/help +metadata_DATA = rarian.document +all: all-am + +.SUFFIXES: +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ + && exit 0; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu docs/Makefile'; \ + cd $(top_srcdir) && \ + $(AUTOMAKE) --gnu docs/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +rarian.document: $(top_builddir)/config.status $(srcdir)/rarian.document.in + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs +install-manualDATA: $(manual_DATA) + @$(NORMAL_INSTALL) + test -z "$(manualdir)" || $(MKDIR_P) "$(DESTDIR)$(manualdir)" + @list='$(manual_DATA)'; for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + echo " $(manualDATA_INSTALL) '$$d$$p' '$(DESTDIR)$(manualdir)/$$f'"; \ + $(manualDATA_INSTALL) "$$d$$p" "$(DESTDIR)$(manualdir)/$$f"; \ + done + +uninstall-manualDATA: + @$(NORMAL_UNINSTALL) + @list='$(manual_DATA)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(manualdir)/$$f'"; \ + rm -f "$(DESTDIR)$(manualdir)/$$f"; \ + done +install-metadataDATA: $(metadata_DATA) + @$(NORMAL_INSTALL) + test -z "$(metadatadir)" || $(MKDIR_P) "$(DESTDIR)$(metadatadir)" + @list='$(metadata_DATA)'; for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + echo " $(metadataDATA_INSTALL) '$$d$$p' '$(DESTDIR)$(metadatadir)/$$f'"; \ + $(metadataDATA_INSTALL) "$$d$$p" "$(DESTDIR)$(metadatadir)/$$f"; \ + done + +uninstall-metadataDATA: + @$(NORMAL_UNINSTALL) + @list='$(metadata_DATA)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(metadatadir)/$$f'"; \ + rm -f "$(DESTDIR)$(metadatadir)/$$f"; \ + done +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ + fi; \ + cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ + else \ + test -f $(distdir)/$$file \ + || cp -p $$d/$$file $(distdir)/$$file \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-am +all-am: Makefile $(DATA) +installdirs: + for dir in "$(DESTDIR)$(manualdir)" "$(DESTDIR)$(metadatadir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: + +html: html-am + +info: info-am + +info-am: + +install-data-am: install-manualDATA install-metadataDATA + +install-dvi: install-dvi-am + +install-exec-am: + +install-html: install-html-am + +install-info: install-info-am + +install-man: + +install-pdf: install-pdf-am + +install-ps: install-ps-am + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: uninstall-manualDATA uninstall-metadataDATA + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic clean-libtool \ + distclean distclean-generic distclean-libtool distdir dvi \ + dvi-am html html-am info info-am install install-am \ + install-data install-data-am install-dvi install-dvi-am \ + install-exec install-exec-am install-html install-html-am \ + install-info install-info-am install-man install-manualDATA \ + install-metadataDATA install-pdf install-pdf-am install-ps \ + install-ps-am install-strip installcheck installcheck-am \ + installdirs maintainer-clean maintainer-clean-generic \ + mostlyclean mostlyclean-generic mostlyclean-libtool pdf pdf-am \ + ps ps-am uninstall uninstall-am uninstall-manualDATA \ + uninstall-metadataDATA + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/docs/help-spec-0.2.xml b/docs/help-spec-0.2.xml new file mode 100644 index 0000000..14e772d --- /dev/null +++ b/docs/help-spec-0.2.xml @@ -0,0 +1,839 @@ +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ + <!ENTITY version "0.2"> + <!ENTITY dtd-version "1.0"> + ]> + +<article id="index"> + <articleinfo> + <title>Help System Specification</title> + <releaseinfo>Version &version;</releaseinfo> + <date>23 November 2006</date> + <authorgroup> + <author> + <firstname>Don</firstname> + <surname>Scorgie</surname> + <affiliation> + <address> + <email>DonScorgie@Blueyonder.co.uk</email> + </address> + </affiliation> + </author> + <author> + <firstname>Roman</firstname> + <surname>Joost</surname> + <affiliation> + <address> + <email>romanofski@gimp.org</email> + </address> + </affiliation> + </author> + <author> + <firstname>Christopher</firstname> + <surname>Lahey</surname> + <othername role="mi">James</othername> + <affiliation> + <address> + <email>clahey@ximian.com</email> + </address> + </affiliation> + </author> + <author> + <firstname>Shaun</firstname> + <surname>McCance</surname> + <affiliation> + <address> + <email>shaunm@gnome.org</email> + </address> + </affiliation> + </author> + <author> + <firstname>Cornelius</firstname> + <surname>Schumacher</surname> + <affiliation> + <address> + <email>schumacher@kde.org</email> + </address> + </affiliation> + </author> + </authorgroup> + </articleinfo> + + <sect1 id="introduction"> + <title>Introduction</title> + <para> + Providing help to the user is one of the most important functions of a + user-friendly desktop system. This document specifies how desktop help + systems can find, navigate, show and search documentation. This includes + application manuals, context-sensitive help and documentation not + associated with a specific application. Documentation can be provided in + in numerous formats, for example Docbook, HTML, PDF and can also be + provided over the net. + </para> + <para> + The goal of this standard is to provide the base for a unified + cross-desktop documentation system. + </para> + + </sect1> + + <sect1 id="goals"> + <title>Goals of the help system</title> + <para> + This help system standard aims at providing help browser developers and + application authors as well as documentation creators the means to + integrate and consistently handle all documentation present on a system. + It doesn't mean to specify any implementation details or to impose any + policies about what type of help browser to use or how exactly the + documentation is organized or formatted. + </para> + <para> + These are the specific goals of the help system specification: + </para> + <itemizedlist> + <listitem> + <para> + Users should be able to choose the help browser of their choice. + </para> + </listitem> + <listitem> + <para> + The help system should impose as little policy as possible on the + help browser, and should expose as little policy as possible to + documenters. + </para> + </listitem> + <listitem> + <para> + It should be simple to place a document in the help system. The help + system shouldn't require anything to be run to register or + unregister a document. That just begs for problems. + </para> + </listitem> + <listitem> + <para> + The help system should not assume anything about the viewing + program. The viewer may not be a graphical program like Yelp or the + KDE Help Center. It may be a print system, a console program, or + some sort of documentation server. + </para> + </listitem> + <listitem> + <para> + Documents should be able to supply meaningful meta data, which help + viewers may be able to use. The meta data format for documents should + be easily extended in a well-defined way. + </para> + </listitem> + <listitem> + <para> + Applications should have a simple and consistent way of accessing + their documentation, independent of the desktop environment. + </para> + </listitem> + <listitem> + <para> + Documents should have a simple and consistent way of referencing other + pieces of documentation, independent of the desktop environment. + </para> + </listitem> + <listitem> + <para> + The help system should be capable of pulling information from other + existing help systems. This way we can have legacy compatibility + with KDE's and GNOME's current systems. Also, this can provide a + consistent means for help viewers to integrate man and info, if they + choose to. + </para> + </listitem> + </itemizedlist> + + </sect1> + + <sect1 id="definitions"> + <title>Definitions</title> + <variablelist> + <varlistentry> + <term>Help System</term> + <listitem> + <para> + The framework for finding, navigating, showing and searching help. + This usually includes a help browser, support for applications + showing manuals and context help. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Help Browser</term> + <listitem> + <para> + An application for browsing all help content which is available on + the system. This usually includes showing a, possibly hierarchical + list, of available documentation, facilitates to search all + documentation and a view of the selected documentation. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Document</term> + <listitem> + <para> + A self-contained piece of documentation. This can for example be an + application manual, a single help page, a complete book or a + website. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Section</term> + <listitem> + <para> + A document may be made up of separate sections. These may be defined + within the document or externally. For more details on this, please + see the <link linkend="Mallard">Additional Sections section</link> + of this document. + </para> + </listitem> + </varlistentry> + </variablelist> + + </sect1> + + <sect1 id="overview"> + <title>Overview</title> + <para> + The help system accesses the documentation by making use of meta data + which accompanies the documentation. This meta data is provided at a + standard location as files whose content is based on the desktop entry + specification. + </para> + <para> + The meta data contains information about the title of the document, where + to find it, what type of format it is and to which categories it belongs. + Based on this information help browsers can provide navigation, search and + display of all documents known to the help system. + </para> + <para> + For making the help system aware of a certain piece of documentation it's + enough to create the meta data file and put it at the appropriate + location. This makes it easy for documentation creators to integrate their + documentation into the help system and also provides a simple way to + integrate third party documentation. + </para> + <para> + More advanced features of help browsers like hierarchical displays of + documents and their content or searching documentation can implemented in + a generic way using the meta data information provided by the help system. + The help system specification doesn't impose any policies or restrictions + how (or if) help browsers should implement these kinds of functionality. + </para> + </sect1> + + <sect1 id="paths"> + <title>Documentation Meta Data</title> + <para> + In order to provide the help system with the information of where to find + individual pieces of documentation and some more meta information, each + document or section is accompanied with a file containing the meta data + using the desktop entry specification (aka a "desktop file"). The desktop + files contain some extended attributes specific to the help system. + </para> + + <para> + Individual documents or sections come with individual desktop files in + order to make packaging easier and not requiring any post-installation + processing. + </para> + + <para> + This section describes, how the meta data files are found by the help + system, what specific entries they contain and how language-specifics are + handled. + </para> + + <sect2 id="meta-data-location"> + <title>Location of meta data</title> + <para> + The help system should read desktop files containing meta data from + <literal>$XDG_DATA_HOME/help/</literal>, followed by + <literal>$XDG_DATA_DIRS/help/</literal> (here, referred to + together as <literal>$LOCATIONS</literal>) using the <ulink + url="http://freedesktop.org/wiki/Standards_2fbasedir_2dspec">XDG + Base Directory Specification</ulink>. If a file with the same name is + found at multiple locations, the first one is used and the + others are ignored. + </para> + + <para> + Sub-directories of <literal>$LOCATIONS</literal> are + scanned recursively (excluding + <literal>$LOCATIONS/LOCALE</literal>) to get all desktop files. + </para> + + <para> + As per the Base Directory Specification, if $XDG_DATA_HOME is empty or + undefined, a path of <literal>$HOME/.local/share</literal> is used. If + <literal>$XDG_DATA_DIRS</literal> is empty or undefined, a default + path of <literal>/usr/local/share/:/usr/share/</literal> should be + used. + </para> + + <para> + The filename for document meta data files consists of a basename and the + ".document" suffix. + </para> + + </sect2> + + <sect2 id="desktop-file-extensions"> + <title>Desktop Entry Fields</title> + <para> + The help system specification uses several standard fields. They are + described in the + <ulink url="http://standards.freedesktop.org/desktop-entry-spec/latest/">desktop + entry specification</ulink>. + </para> + <para> + All entries below belong to the group header "Document". The "Required?" field states + whether the key is required or option. If it is optional, sane defaults must be provided + by the help system (identified in footnotes). + + <table> + <title>Standard Desktop Entry Fields used by Help System</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Key</entry> + <entry>Description</entry> + <entry>Value Type</entry> + <entry>Required?</entry> + </row> + </thead> + <tbody> + <row> + <entry><varname>Name</varname></entry> + <entry> + Title of document. + </entry> + <entry>localestring</entry> + <entry>Yes</entry> + </row> + <row> + <entry><varname>Comment</varname></entry> + <entry> + Short description of document. + </entry> + <entry>localestring</entry> + <entry>No<footnote><para>Defaults to empty</para></footnote></entry> + </row> + <row> + <entry><varname>Icon</varname></entry> + <entry> + Name of icon for document. As per the desktop entry spec, + this may be either an icon name or a filename. If the icon is + named (i.e. no path), the icon is found using the algorithm + defined in + <ulink url="http://freedesktop.org/wiki/Standards/icon-theme-spec"> + the icon naming spec</ulink> + </entry> + <entry>string</entry> + <entry>No<footnote><para>Defaults to empty</para></footnote></entry> + </row> + <row> + <entry><varname>Categories</varname></entry> + <entry> + Categories the document belongs to. For possible values see the + <ulink url="http://standards.freedesktop.org/menu-spec/latest/"> + menu entry specification</ulink>. Help browsers + can base a hierarchical view on the categories. + </entry> + <entry>semi-colon separated strings</entry> + <entry>Yes</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + + <para> + In addition to the standard fields the meta data files uses several + extensions to the desktop entry standard within this group, which + contain meta data specific to the help system. The keys of all + help system specific entries in this group are prefixed with "Doc". + </para> + + <table> + <title>Extended Desktop Entry Fields used by Help System</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Key</entry> + <entry>Description</entry> + <entry>Value Type</entry> + <entry>Required?</entry> + </row> + </thead> + <tbody> + <row> + <entry><varname>DocPath</varname></entry> + <entry> + Location of document. In addition to the standard URI schemes + like http: and file: the help system can support non-standard + URI schemes to access specific kinds of documentation which + aren't accessible by a standard URI. In particular the following + non-standard URI schemes can be supported: + <simplelist> + <member>help: KDE manual identified by app name,</member> + <member>ghelp: GNOME manual identified by app name,</member> + <member>man: man page,</member> + <member>info: info page</member> + </simplelist> + </entry> + <entry>URI (locale-dependent)</entry> + <entry>Yes</entry> + </row> + <row> + <entry><varname>DocType</varname></entry> + <entry> + Mime type of document. + </entry> + <entry>string</entry> + <entry>Yes</entry> + </row> + + <row> + <entry><varname>DocWeight</varname></entry> + <entry> + A number indicating the position of the document within the list + of siblings. A greater weight indicates that the document is + 'heavier', thus shown below 'lighter' documents. The default + weight is 0. Negative values are legal. When assigning weights + to documents it should be made sure that enough room is left to + make it possible to put other documents before or after the + documents. + </entry> + <entry>int</entry> + <entry>No<footnote><para>Defaults to 0</para></footnote></entry> + </row> + <row> + <entry><varname>DocIdentifier</varname></entry> + <entry> + Unique identifier for document. Entries should be an R-DNS style, + for example "org.gnome.user-guide" or "org.kde.konqueror". + If this isn't present, it defaults to "org.other.<basename>" + </entry> + <entry>string</entry> + <entry>No<footnote><para>Defaults to org.other.<basename></para></footnote></entry> + </row> + <row> + <entry><varname>DocLang</varname></entry> + <entry> + Language of document. This entry is only considered if multiple + locale strings are not defined within the file. + </entry> + <entry>language code</entry> + <entry>No<footnote><para>Defaults to "en"</para></footnote></entry> + </row> + <row> + <entry><varname>DocHeritage</varname></entry> + <entry> + The scrollkeeper seriesid, used for backwards compatibility. + If the document is new or does not have a current scrollkeeper seriesid, + this field is not required. Should be of the R-DNS form + "org.scrollkeeper.<seriesid>". + </entry> + <entry>string</entry> + <entry>No<footnote><para>Defaults to empty</para></footnote></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + Fields defined in a document meta data file, other than those defined here, + are invalid and should be ignored. + </para> + </sect2> + + <sect2 id="language-specific-docs"> + <title>Language-specific documentation</title> + <para> + All desktop file fields can be language-specific (e.g. "Name[fr]"). + This is especially useful for the <varname>title</varname> and + <varname>comment</varname> fields to + provide translations of the meta data. It can also be used for the + <varname>DocPath</varname> field, to reference translated versions of + documents. An alternative to language-specific fields is to provide a + separate desktop file for each translated version of the document. + Which alternative is the best one is often determined by packaging + requirements. + </para> + + <para> + Language-specific desktop files are read from + <literal>$XDG_DATA_DIRS/help/LOCALE/LC</literal>, where LC is a two-letter + ISO language code (TODO: reference language code specification). The + files in language-specific directories are read according to the same + rules as non-language-specific files. Locale specific files take + priority over regular entries within the same base directory. + </para> + <para> + If there are multiple versions of the same document in different + languages, there can be multiple desktop files with the same name, + located within <literal>$XDG_DATA_DIRS/help/locale/LC</literal>. It is + up to the help system to decide which file is to be used based on the + preferences of the user. This preference is defined by the + <literal>$LANGUAGE</literal> environment variable. + </para> + </sect2> + + <sect2 id="Mallard"> + <title>Additional Sections</title> + <para> + In addition to "full" documents described previously, documents can be + made up from one or more "sections". + </para> + <para> + These sections may either be specified within the document desktop file, + or in their own desktop file. These section files are stored in the + $XDG_DATA_DIRS/help (sub-)directories and have filenames consisting of + a basename and the ".section" suffix. + </para> + <para> + As before, the first entry found is used and subsequent entries are ignored. + In the special case where a ".section" file defines a section already found in + a document file and both files are in the same directory, the new + section overloads the previously defined section. + </para> + <para> + similarly, language-specific versions of section files may be supplied + in <literal>$XDG_DATA_DIRS/help/LOCALE/LC</literal>. These files follow + the same rules as previously outlined. + </para> + <para> + The entries within sections belong to the "Section" group header and are described below. + All entries are prefixed by "Section". + </para> + + <table> + <title>Section Desktop Entry Fields used by Help System</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Key</entry> + <entry>Description</entry> + <entry>Value Type</entry> + <entry>Required?</entry> + </row> + </thead> + <tbody> + <row> + <entry><varname>SectionName</varname></entry> + <entry> + The title of the section + </entry> + <entry>localestring</entry> + <entry>Yes</entry> + </row> + <row> + <entry><varname>SectionIdentifier</varname></entry> + <entry> + The ID of the section for referencing within the document + </entry> + <entry>string</entry> + <entry>Yes</entry> + </row> + <row> + <entry><varname>SectionDocument</varname></entry> + <entry> + The parent document to which the section belong. This is + in the form of the parent documents "DocIdentifier" in the + R-DNS style described above. For subsections (or lower), the + R-DNS must include the parent section path. E.g. "org.gnome.user-guide.CDBurning" + would describe a section from the GNOME user guide that is a child of + the "CDBurning" section. If the section is defined within the + master document meta data file, the document "DocIdentifier" may + be neglected. + </entry> + <entry>string</entry> + <entry>Yes<footnote>This entry is only required for sections defined + in a separate file from the main document. For sections defined + within the document meta data file, the SectionDocument is implied to + be the current document.</footnote></entry> + </row> + <row> + <entry><varname>SectionPath</varname></entry> + <entry> + The path to the file containing the section. This can be either relative + to the parent document's path (if no full path is given) or an absolute file path + </entry> + <entry>URI (locale-dependent)</entry> + <entry>Yes</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + </sect1> + + <sect1 id="doc-location"> + <title>Location of Documentation</title> + <para> + The help standard doesn't imply any policy where the files containing + the actual documentation are located. The only requirement is that the + DocPath from the meta data files points to the right location. + </para> + + <para> + If the DocPath is a full URI, it is taken as it is. Absolute paths are + promoted to "file:" URIs. + </para> + + </sect1> + + <sect1 id="identifying-referencing"> + <title>Identifying and Referencing help</title> + <para> + The help system has to be able to identify and reference help documents. + This is needed for applications to provide manuals or context-sensitive + help or to cross-link documents. It is also needed for locating + documentation from within the desktop meta data files. + </para> + + <sect2 id="identifiers"> + <title>Identifiers</title> + <para> + Each document is uniquely identified by an identifier. The + identifier is defined within the meta data file as the + DocIdentifier entry. The identifier has to be unique on the system. + If there are multiple language versions of a + document all of them are identified by the same identifier. + </para> + + <para> + The unique identifier is used within the help system to determine if + duplication has occurred. If two meta data files have the same identifier, + first one discovered by the help system is used. In the special + case of two meta data files in + the same directory sharing an identifier, the first discovered by the + help system is used (which may vary depending on system). + </para> + </sect2> + <sect2 id="calling-help"> + <title>Invoking the Help Browser</title> + <para> + If a desktop environment provides a help browser it has to provide a + program "xdg_help" in the binary search path which starts the help + browser. The program should handle URIs and document identifiers as + command line options. When invoked with a URI or command line option, + the program should open the relevant document and section specified. + </para> + + <para> + The "xdg_help" program may also be invoked through a dbus call to + "org.freedesktop.help_system" on the session bus. The program must + respond to two signals. + <variablelist> + <varlistentry><term><para>open_document (DocIdentifier: string)</para> + </term> + <listitem>Open the given identifier</listitem> + </varlistentry> + <varlistentry> + <term><para>close_document (DocIdentifier: string)</para></term> + <listitem>Close the given identifer, if an open window exists + currently displaying the document with the given identifier + </listitem> + </varlistentry> + </variablelist> + (Brackets denote required input parameters and types). Both methods are + asynchronous and are not expected to return anything. + </para> + + <para> + Sections of documents may be requested by extending the document + identifier to include the section id. If the document has registered + sections, the section identifier may point to one of these. If no + registered sections are available, the section identifier is assumed to + point to an internal (implicit) section within the found document / + section and treated as such when the document is displayed. + </para> + + <para> + In order to call the help system from within an application, several + options are available: + <itemizedlist> + <listitem>Issue the command "xdg_help <uri>" through system() or + similar</listitem> + <listitem>Issue the command "xdg_help <DocIdentifier>" through + system() or similar</listitem> + <listitem>Issue a dbus command of "open_document" with the associated + docidentifier as an argument to "org.freedesktop.help_system" + on the session bus. + </listitem> + </itemizedlist> + </para> + <para> + In the first case, the given URI should be opened without reference to + any meta data files available. In the second and third cases, the + help system should find the appropriate meta data file and use the + specified docpath from that meta data. + </para> + </sect2> + </sect1> + + <appendix id="examples"> + <title>Example Help System Meta Data Files</title> + <para> + This appendix gives examples of meta data desktop files for use within + the help system. + </para> + <para> + A basic docbook desktop file with German translation (with apologies for the translation). + </para> + <programlisting> +# Beanstalk manual description +[Document] +Name=The Beanstalk Manual +Name[de]=Das Bohnenstange-Handbuch +Comment=Jack likes beanstalks. With this manual, you too can grow you're own +beanstalk. Who knows, you may even find a golden egg or two! +Comment[de]=Jack mag Bohnenstangen. Mit diesem Handbuch kannst du dich wachsen +auch sollst Bohnenstange besitzen. Wer weiß, kannst du ein goldenes Ei oder zwei +sogar finden! +DocPath=file://usr/share/help/C/beanstalk/beanstalk.xml +DocPath[de]=file://usr/share/help/de/beanstalk/beanstalk.xml +DocType=application/docbook+xml +Categories=GNOME;Building;Construction +DocIdentifier=org.gnome.beanstalk +# Displaces a document previously registered with scrollkeeper +DocHeritage=org.scrollkeeper.2a958241-f90e-4aca-a201-cc5d21b7b6ce + </programlisting> + + <para> + Another manual (with different keys), installed as a pdf. No translations. + </para> + <programlisting> +[Document] +# Glermo's proprietary app. Installed as a pdf to stop thieving. +# Comments are lines that begin with a '#' symbol. +Name=Glermo's Magic Beanstalk Recipes +Comment=Tired of the semi-finished Beanstalk from Jack? With Gelrmo, +you don't need to worry, we're already finished! +# Named icons don't need a path. This assumes the system knows the icon +# exists. +Icon=glermo-beanstalk +DocPath=file:///opt/glermo/help/glermo.pdf +DocType=application/pdf +# We want to be first on the list, dag nabbit +DocWeight=-50 +Categories=Construction +DocIdentifier=org.other.glermo + </programlisting> + + <sect2 id="mallard-eg"> + <title>Documentation with Defined Sections</title> + <para> + In this section, one "document" is described - "GNOME User Guide", + comprising of 2 sections - "Desktop Tools" and "CD Burning". I'll forgo + you the agony of my translations. + </para> + <programlisting> +# First the document. This would be user-guide.desktop +[Document] +Name=GNOME User Guide +Comment=Learn how to use you're GNOME desktop +DocPath=file://usr/share/gnome/help/user-guide/C/user-guide.xml +# Made up mime type. Do we need to define a mime type for Mallard docs? +DocType=application/mallard+xml +Categories=GNOME +# We really want to be listed first. For real reasons this time, +# not just vanity +DocWeight=-5 +DocIdentifier=org.gnome.user-guide + +# Define one section +[Section] +SectionName=Desktop Tools +# Don't give a full path. The full path is found using the DocPath given +# above. The complete path is /usr/share/gnome/help/user-guide/C/desktop-tools.xml +SectionPath=desktop-tools.xml +SectionIdentifier=desktoptools +# Don't need to define section document as we're defined in the parent +# docs meta data file + +# Now we define the second section +[Section] +SectionName=CD Burning +SectionPath=cdburning.xml +SectionIdentifier=cdburning + </programlisting> + + <para> + In the same directory, someone else has defined a new section file, defining a new "CD Burning" section. + This new section contains a new subsection - "DVD Burning". This new version will overwrite the + section defined above. + </para> + <programlisting> +# The new CD Burning section. This would be the file cdburning.section +[Section] +SectionName=Burning Media +SectionIdentifier=cdburning +SectionDocument=org.gnome.user-guide +# Sections defined outside the main document meta data file +# almost certianly want to define the location with an absolute path +SectionPath=file://tmp/testing/cdburning.xml +SectionChildren=dvdburning + +# Define the dvd burning section here as well +SectionName=Burning a DVD +SectionIdentifier=dvdburning +# Not strictly necessary as we already know the parent (above), but it won't +# hurt to define it anyway +SectionPath=file://tmp/testing/dvdburning.xml +# Parent is the CD Burning section. Add that to the Document ID as below +SectionDocument=org.gnome.user-guide.cdburning + </programlisting> + </sect2> + </appendix> + <appendix id="example-calls"> + <title>Example Help System Calls</title> + <para> + This section demonstrates various methods of requesting the help system + open a particular document or section. This is intended to show how + application authors would implement requests. All code here is + psuedo-code. + </para> + <para> + An example of a simplistic call to help from a program requesting that the + user manual for "The Beanstalk Program" be opened. + </para> + <programlisting> +# User requested help. Open using dbus. +bus = get_dbus_session_bus () +bus.send_signal (bus, "org.freedesktop.help_system", + "open_document", "org.gnome.beanstalk"); + </programlisting> + <para> + The following example shows how to request subsections and a possible + example of requesting a filename be opened. + </para> + <programlisting> +if (installed) + # We're running in installed mode, request help using the proper route + bus.send_signal (bus, "org.freedesktop.help_system", + "open_document", "org.gnome.beanstalk.Growing" +else + # We're uninstalled. The help probably isn't registered. If it is + # it's probably old. Request using the filename instead. + system ("xdg_help ../help/C/beanstalk.xml#Growing") + </programlisting> + <para> + Finally, for the app that doesn't want to depend on dbus, we present yet + another method of accessing help (same section as above) + </para> + <programlisting> +# Help requested. Opening. +system ("xdg_help org.gnome.beanstalk.Growing") + </programlisting> + </appendix> +</article> diff --git a/docs/index.xhtml b/docs/index.xhtml new file mode 100644 index 0000000..dc06aaf --- /dev/null +++ b/docs/index.xhtml @@ -0,0 +1,39 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE html +PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<title>Rarian Reference Manual</title> +</head> +<body> +<h1>Rarian Reference Manual v0.6</h1> +<hr/> +<h2>Overview</h2> +<p> +This manual describes version 0.6 of Rarian, a documentation meta-data +library. It is split into three sections, which are relevant for +different people. The first section covers writing Rarian meta-data +files and is useful for people wishing their documentation to be +visible in applications using Rarian.</p> + +<p>The second section describes the Rarian library. This details the +available API and requirements for using it. This section is aimed at +developers wishing to use the power of Rarian in their applications.</p> + +<p>The final section describes the scrollkeeper compatibility stuff in +Rarian and how to take advantage of this. It isn't really useful for +anyone, but is included for completeness.</p> +<!--<br/>--> +<hr/> +<h2>Contents</h2> +<ul> +<li><a href="license.xhtml">Preamble</a></li> +<li><a href="rar-mdf.xhtml">Writing Rarian meta-data files</a></li> +<li><a href="rar-lib.xhtml">Using the Rarian library</a></li> +<li><a href="rar-skcompat.xhtml">Scrollkeeper compatibility</a></li> +</ul> + +</body> +</html> + diff --git a/docs/omf_equivalence.txt b/docs/omf_equivalence.txt new file mode 100644 index 0000000..17c1c6e --- /dev/null +++ b/docs/omf_equivalence.txt @@ -0,0 +1,244 @@ +Applications Broken + Amusement Game + Education Education + Arts Art + Computer Science ComputerScience + English Languages + Language Languages + Maths Math + Music Music + Science Science + Technology ComputerScience + Testing Broken + Other Education + Games Game + Arcade ArcadeGame + Board BoardGame + First Person Shooters RolePlay + Puzzles LogicGame + Fighting ArcadeGame + Role-Playing RolePlay + Simulation Simulation + Strategy StrategyGame + Other Game + Internet Network + Chat Chat + Email Email + Fax Network + File Sharing FileTransfer + FTP FileTransfer + Internet Phone Telephony + Messaging InstantMessaging + News News + Video Conferencing VideoConference + Web WebBrowser + Other Network + Multimedia AudioVideo + Graphics Video + 3D Modelling 3DGraphics + 3D Rendering 3DGraphics + CAD Engineering + Capture Recorder + Conversion AudioVideoEditing + Drawing 2DGraphics + Editing 2DGraphics + Viewing Viewer + Other Video + Sound Audio + Analysis AudioVideoEditing + CD Mastering DiscBurning + Conversion AudioVideoEditing + Editing AudioVideoEditing + MIDI Midi + Mixers Mixer + Players Player + Recording Recorder + Speech Audio + Other Audio + Video Video + Capture Recorder + Conversion AudioVideoEditing + Display Player + Editing AudioVideoEditing + Other Video + Other AudioVideo + Office Office + Calendar Calendar + Data Processing Office + Database Database + Email Email + Financial Finance + PIM ContactManagement + Plotting Office + Presentation Presentation + Publishing Publishing + Web Publishing Publishing + Word Processing WordProcessor + Other Office + Scientific Science + Astronomy Astronomy + Astrophysics Astronomy + Biology Biology + Chemistry Chemistry + EDA Engineering + Genetics Biology + Math Math + Physics Physics + Visualisation DataVisualisation + Other Science + Security Security + Cryptography Security + Other Security + Text Editors TextEditor + CLI TextEditor + GUI TextEditor + Other TextEditor + Utilities Utility + Archiving Archiving + Calculating Calculator + Clocks Clock + Compression Compression + File Utilities FileTools + Monitors Monitor + Printing Printing + Terminals TerminalEmulator + Text Utilities ConsoleOnly + Other Utility + X Utility + Configuration DesktopSettings + Fonts DesktopSettings + Login Managers DesktopSettings + Screensavers Screensaver (?) + Window Managers DesktopSettings + Other DesktopSettings +CDE DesktopSettings +Development Development + Databases Database + Development Tools Development + Build Tools Building + Code Generators Development + Configuration Development + Debuggers Debugger + IDEs IDE + Packaging Development + Profiling Profiling + RAD Development + Version Control RevisionControl + Other Development + Environments Development + ADA Development + C Development + C++ Development + GNOME Development + GTK+ Development + gtk++ Development + Java Development + KDE Development + Perl Development + Python Development + Qt Development + Tcl/Tk Development + WebML Development + Other Development + Kernels Development + FreeBSD Development + Linux Development + NetBSD Development + Other Development + Libraries Development + System Calls Development + Other Development +General Broken + Licenses Documentation + Linux Documentation + Distributions Documentation + Caldera Core + Debian Core + Mandrake Core + Red Flag Core + Red Hat Core + Slackware Core + SuSE Core + Other Core + General Documentation + Other Documentation + Other Core +GNOME GNOME + Core Desktop Core + Applets Applet + Amusement Game + Clock Clock + Monitors Monitor + Multimedia AudioVideo + Network Network + Utility Utility + Applications GNOME + Utilities Utility + Development Development + Applications Development + Introductory Development + Tutorials Development + White Papers Development + Games Game + Graphics Graphics + Internet Network + Multimedia AudioVideo + Settings Settings + System System + Other GNOME +KDE KDE + Utilities Utility + Applications KDE + Games Game + Graphics Graphics + Internet Network + Multimedia AudioVideo + Settings Settings + System System + Programs KDE + Development Development + Other KDE +System System + Administration Settings + Backups Archiving + Local Archiving + Remote Archiving + Filesystems Filesystem + Networking Network + AppleTalk Network + PPP Network + SMB Network + TCP/IP Network + DNS Network + Other Network + Users Settings + Other Settings + Configuration Settings + Config Files Settings + Configuration Tools Settings + Other Settings + Hardware HardwareSettings + Processor HardwareSettings + Storage HardwareSettings + Video HardwareSettings + Input Devices HardwareSettings + Networking HardwareSettings + PCI/ISA/PCMCIA HardwareSettings + Other HardwareSettings + Package Management PackageManager + Security Security + Firewall Security + Intrusion Detection Security + Virus Security + Other Security + Services System + HTTP System + FTP System + SMB System + SSH System + Telnet System + Syslog System + BIND System + Printing Printing + Other System + Other System diff --git a/docs/rar-lib.xhtml b/docs/rar-lib.xhtml new file mode 100644 index 0000000..a38594e --- /dev/null +++ b/docs/rar-lib.xhtml @@ -0,0 +1,360 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE html +PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<title>LibRarian Reference</title> +</head> +<body> +<p><a href="index.xhtml">return to index</a></p> + +<h1>LibRarian Reference</h1> + +<p>This section gives an overview of the Rarian Library. It outlines +how to harness the power of Rarian and gives an overview of the +available functions.</p> + +<p><strong>Note</strong>: Rarian is currently API-unstable. You are +advised to explicitly check and use exact versions of Rarian</p> + +<h2>Including the library</h2> + +<p>You can include the library in your application by using +pkg-config to set the correct include and lib flags. The name to +check for is "rarian". You should check for exact versions at this +stage as Rarian API is liable to change in future releases.</p> + +<p>Alternatively, you can set the cflags and libs yourself. The +correct include path is ">prefix</include/rarian" and the +library name is "rarian".</p> + +<h2>Overview of Rarian library makeup</h2> + +<p>Rarian is currently split into three parts:</p> +<ul> +<li>The main documents access functions</li> +<li>The man page access functions</li> +<li>The info page access functions</li> +</ul> + +<p>which gives access to the three different forms of documentation +available to Rarian. Each of these is discussed in the relevant +section here.</p> + +<h2>Commonalities</h2> + +<p>Each of the three "sections" of LibRarian share commonalities. The +primary one is initialisation. In all three cases, initialisation +happens implicitly on the first call requiring access to the internal +list of documents. This means the documents should always be +available when calling into the functions.</p> + +<h2>Main Documents</h2> + +<p>Main documents are defined by anything with an equivalent "scroll" +file. This documentation can be of any form and Rarian can provide +lists of the documentation. The scroll files are picked up from +$XDG_DATA_DIRS/help and form the basis for most of Rarian.</p> + +<p>The following documents can be accessed by including the +"rarian.h" file.</p> + +<h3>Preamble</h3> + +<p>Functions returning meta-data do so in a struct, the RrnReg. The +definition for this struct looks like:</p> + +<pre> +struct _RrnReg +{ + char *name; + char *uri; + char *comment; + char *identifier; + char *type; + char *icon; + char **categories; + int weight; + char *heritage; + char *omf_location; + char *ghelp_name; + char *lang; + RrnSect *children; +}; +</pre> + +<p>Most of these fields are self-explanatory and match up with the +fields in the scroll files. The ones that do not are described +below:</p> + +<dl> +<dt>heritage</dt> +<dd>The x-DocHeritage field of the meta-data file. Should generally +be ignored.</dd> +<dt>omf_location</dt> +<dd>The x-Scrollkeeper-omf-loc field of the meta-data file. Should +generally be ignored.</dd> +<dt>ghelp_name</dt> +<dd>The abbreviated name of the meta-data file. Using the beanstalk +example, this field would be filled with "beanstalk". When a user +requests a "ghelp" uri, this field should be compared to the requested +URI (sans the ghelp prefix). Otherwise, this field should be ignored.</dd> +<dt>children</dt> +<dd>When a document consists of sections, this will contain a pointer +to the lists of sections. <strong>TODO:</strong> Add information +about sections.</dd> +</dl> + +<p><strong>Note</strong>: The returned structure must never be freed.</p> + +<h3>For each functions</h3> + +<p><strong>rrn_for_each (RrnForeachFunc funct, void * +user_data)</strong></p> +<p>Iterates through each available document in turn and calls +<em>funct</em> for each. If <em>funct</em> returns <em>FALSE</em>, +iteration is stopped immediately.</p> + +<p><strong>void rrn_for_each_in_category (RrnForeachFunc funct, char * category, + void *user_data)</strong></p> +<p>Iterates through each document in <em>category</em> and calls +<em>funct</em> for each. If <em>funct</em> returns <em>FALSE</em>, +iteration is stopped immediately.</p> + +<p>The prototype of RrnForeachFunc looks like:</p> +<pre>typedef int (* RrnForeachFunc) (void * reg, void *data);</pre> + +<p>The <em>void *reg</em> will be a pointer to the RrnReg for the +entry as described above. The <em>void *data</em> parameter is the +<em> user_data</em> parameter passed into the for-each function.</p> + +<h3>Finding functions</h3> + +<p><strong>RrnReg * rrn_find_entry_from_uri (char *uri)</strong></p> + +<p>Finds the relevant entry from the <em>uri</em>. This simply +compares the <em>uri</em> to the <em>uri</em> field of the RrnReg and +returns the <em>RrnReg</em> if they match. This will find the first +match and ignore further matches. If no match is found, <em>NULL</em> is returned.</p> + +<p><strong>RrnReg * rrn_find_from_name (char *name)</strong></p> + +<p>Finds the relevant entry from the <em>name</em>. This simply +compares the <em>name</em> to the <em>name</em> field of the RrnReg and +returns the <em>RrnReg</em> if they match. This will find the first +match and ignore further matches. If no match is found <em>NULL</em> +is returned.</p> + +<p><strong>RrnReg * rrn_find_from_ghelp (char *ghelp)</strong></p> + +<p>Finds the relevant entry from the <em>ghelp</em>. This simply +compares the <em>ghelp</em> to the <em>ghelp_name</em> field of the RrnReg and +returns the <em>RrnReg</em> if they match. This will find the first +match and ignore further matches. The passed in parameter +<em>ghelp</em> must have the "ghelp:" removed from the front of the +URI. If no match is found, <em>NULL</em> is returned.</p> + +<h3>Misc. functions</h3> + +<p>Rarian provides several miscellaneous functions in this sections. +These are described here.</p> + +<p><strong>void rrn_set_language (char *lang_code)</strong></p> + +<p>By default, Rarian will set itself up using the $LANGUAGE +environment variable. You can override this behaviour by calling this +function with <em>lang_code</em> set to the desired language. +Multiple language codes can be specified using colon-delimiting. When +called, this function will re-initialise the internal list of +documents to the desired language.</p> + +<p><strong>void rrn_shutdown ()</strong></p> + +<p>This function shuts down Rarian, freeing any used memory. This is +generally not needed, though may be useful for low-memory situations +when it is known that Rarian will not be necessary again.</p> + +<h2>Man pages</h2> + +<h3>Preamble</h3> + +<p>Rarian provides access to installed man pages on the system. This +functionality can be accessed by including the "rarian-man.h" +file.</p> + +<p>As with the main documents, functions return structs containing +meta-data, the <em>RrnManEntry</em> struct, as described below:</p> + +<pre> + typedef struct _RrnManEntry { + char *name; + char *path; + char *section; + char *comment; + } RrnManEntry; +</pre> + +<p>Each of these fields are self-explanatory.</p> + +<h3>For each functions</h3> + +<p><strong>void rrn_man_for_each (RrnManForeachFunc funct, void * +user_data)</strong></p> + +<p>This function iterates through all man pages and calls +<em>funct</em> for each one. If <em>funct</em> returns FALSE, +iteration is stopped immediately.</p> + + +<p><strong>void rrn_man_for_each_in_category (char *category, +RrnManForeachFunc funct, void * user_data)</strong></p> + +<p>Iterates through each man page within <em>category</em> and calls +<em>funct</em> for each one. If <em>funct</em> returns FALSE, +iteration is stopped immediately. Category names can be found by +calling <em>rrn_man_get_categories</em>, described below.</p> + +<p>The prototype for the RrnManForeachFunc is:</p> +<p><strong>typedef int (* RrnManForeachFunc) (void * reg, void +*data)</strong></p> +<p>where <em>reg</em> is a pointer to the <em>RrnManEntry</em> and +<em>data</em> is the <em>user_data</em> passed in to the for-each +function.</p> + +<h3>Find functions</h3> + +<p><strong>RrnManEntry *rrn_man_find_name (char *name, char +*sect)</strong></p> + +<p>Locates the man page entry with the name <em>name</em> and returns +the relevant <em>RrnManEntry</em>. If <em>sect</em> is non-NULL, only +entries in <em>sect</em> will be considered. If no entry is found, +<em>NULL</em> is returned.</p> + +<h3>Misc. Functions</h3> + +<p><strong>char **rrn_man_get_categories (void)</strong></p> +<p>Returns an a list of <em>char *</em>s which describe the categories +available in Rarian. The final entry in the list is <em>NULL</em></p> + +<p><strong>void rrn_man_shutdown ()</strong></p> + +<p>Shuts down and frees all memory used by the man page section of +Rarian.</p> + +<h2>Info Pages</h2> + +<h3>Preamble</h3> + +<p>Rarian provides access to info pages available on the system by +parsing the info "dir" file to gather the available documents. All +functions to handle info meta-data can be accessed by including the +"rarian-info.h" file. Functions returning meta-data return a <em>RrnInfoEntry</em> struct, +which is declared as:</p> + +<pre> + typedef struct _RrnInfoEntry { + char *name; + char *shortcut_name; + char *base_filename; + char *base_path; + char *section; + char *doc_name; + char *comment; + RrnInfoCompression compression; + char *category; + } RrnInfoEntry; +</pre> + +<p>The elements are described as:</p> + +<dl> +<dt>name</dt> +<dd>The base name of the actual file. This should generally not be used.</dd> +<dt>shortcut_name</dt> +<dd>Currently unused</dd> +<dt>base_filename</dt> +<dd>The filename of the initial document. This should be the file to parse.</dd> +<dt>base_path</dt> +<dd>The path where the document lives.</dd> +<dt>section</dt> +<dd>The section of the document the entry points to (like an anchor in +html documents)</dd> +<dt>doc_name</dt> +<dd>The "title" of the entry. This should be used for table of +content generation.</dd> +<dt>compression</dt> +<dd>Described below.</dd> +<dt>category</dt> +<dd>The category the document belongs in. A list of categories can be +found using rrn_info_get_categories, described below.</dd> +</dl> + +<h4>Compression</h4> + +<p>Rarian provides a guess at the compression used for the info +files in the "compression" field of the RrnInfoEntry struct. This can +be one of the following enum (defined in rarian-info.h)</p> + +<pre> + typedef enum _RrnInfoCompression { + INFO_ENCODING_NONE = 0, + INFO_ENCODING_GZIP, + INFO_ENCODING_BZIP, + INFO_ENCODING_LZMA, + INFO_ENCODING_UNKNOWN, + } RrnInfoCompression; +</pre> + +<h3>For each functions</h3> + +<p><strong>void rrn_info_for_each (RrnInfoForeachFunc funct, void * +user_data)</strong></p> + +<p>Iterates over all info documents available and calls <em>funct</em> +for each one. If <em>func</em> returns <em>FALSE</em>, iteration is +stopped immediately.</p> + + +<p><strong>void rrn_info_for_each_in_category (char *category, RrnInfoForeachFunc funct, void * user_data)</strong></p> + +<p>Iterates over all info documents available in the category +<em>category</em> and calls <em>funct</em> +for each one. If <em>func</em> returns <em>FALSE</em>, iteration is +stopped immediately. A list of available categories can be found +using rrn_info_get_categories described below.</p> + +<p>The prototype for <em>RrnInfoForeachFunc</em> looks like:</p> + +<p><strong>typedef int (* RrnInfoForeachFunc) (void * reg, void +*data)</strong></p> + +<p>where <em>reg</em> is the <em>RrnInfoEntry</em> associated with the +document and <em>data</em> is the <em>user_data</em> element passed +into the for-each function.</p> + +<h3>Finding functions</h3> + +<p><strong>RrnInfoEntry *rrn_info_find_from_uri (char *uri, char +*section)</strong></p> + +<p>Iterates through each entry in <em>section</em> and searches for +the document matching <em>uri</em>. If <em>section</em> is +<em>NULL</em>, all sections are searched. If no match is found, +<em>NULL</em> is returned.</p> + +<h3>Misc. Functions</h3> + +<p><strong>char **rrn_info_get_categories (void)</strong></p> + +<p>Returns a list of available categories. The list is +NULL-terminated and must not be freed.</p> + +<p><strong>void rrn_info_shutdown ()</strong></p> + +<p>Shuts down and frees all memory used by Rarian info stuff.</p> + + +</body> +</html> diff --git a/docs/rar-mdf.xhtml b/docs/rar-mdf.xhtml new file mode 100644 index 0000000..f6f2d5c --- /dev/null +++ b/docs/rar-mdf.xhtml @@ -0,0 +1,160 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE html +PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<title>Writing Rarian Meta-data files</title> +</head> +<body> +<p><a href="index.xhtml">return to index</a></p> +<h2>Overview</h2> +<p>Rarian meta-data files are desktop files as defined by the proposed +XDG help system spec (a copy of which is distributed with the Rarian +source tarball). A copy of specification on which this version of +Rarian is based can also be found +<a href="http://www.gnome.org/~dscorgie/help-spec-0-2.html">here</a>.</p> + +<p>This section describes how to write the meta-data files and how to +ensure they are picked up by the Rarian library.</p> + +<p><strong>WARNING</strong>: The meta-data format is not currently +complete and is liable to change in incompatible ways in future +releases. It is strongly recommended to use the <a +href="rar-skcompat.xhtml">scrollkeeper compatibility mode</a> at present.</p> + +<hr/> +<h2>The basic structure</h2> +<p>A sample meta-data file looks like:</p> +<quote> +<p># An example meta-data scroll file - beanstalk.document</p> +<p>[document]</p> +<p>Name=The Beanstalk Manual</p> +<p>Name[de]=Das Beanstalk Manual</p> +<p>DocIdentifier=org.freedesktop.beanstalk</p> +<p>Categories=Utility;Finance</p> +<p>DocPath=file:///usr/share/fdo/help/beanstalk/C/beanstalk.html</p> +<p>DocPath[de]=file:///usr/share/fdo/help/beanstalk/de/beanstalk.html</p> +<p>DocType=application/xhtml+xml</p> +<p>Comment=Beanstalk provides access to golden eggs. Climb it and find +your destiny</p> +<p>Comment[de]=German language not known. Sorry.</p> +</quote> + +<h3>Anatomy</h3> +<p>The above file introduces most elements of the meta-data file +format.</p> +<ul> +<li>Comments are marked as lines beginning with a '#' character and +are ignored by the parser.</li> +<li>Section names are encased in square brackets ([ ]) beginning a +line. A [document] section is required to be valid.</li> +<li>Fields are of the form "Name=value"</li> +<li>Other languages can be included by specifying the language type in +square brackets at the end of the name: "Name[lang]=value"</li> +<li>Key names are case-sensitive. "Name" is not the same as "name".</li> +<li>Any unknown keys are ignored.</li> +<li>A section continues until another section or end-of-file is +encountered</li> +</ul> + +<h3>Recognised Fields</h3> +<p>The [document] section of meta-data files can contain a number of +fields, some of which are required. This section gives details of +what fields are available and what they do. Fields marked as +<strong>strong</strong> are necessary.</p> + +<dl> +<dt><strong>Name</strong></dt> +<dd>The title of the document</dd> +<dt><strong>DocPath</strong></dt> +<dd>The path to the file. This should be in the form of a URI as above.</dd> +<dt><strong>DocType</strong></dt> +<dd>The mime type of the document.</dd> +<dt>Comment</dt> +<dd>Typically, help browsers will give a short description of the +document to allow people to determine whether they want to look at the +document. This is what is displayed</dd> +<dt>Icon</dt> +<dd>The icon associated with the document, if there is one.</dd> +<dt><strong>Categories</strong></dt> +<dd>A semi-colon separated list of categories the document is relevant +to. The available categories can be found in the <a +href="http://standards.freedesktop.org/menu-spec/latest/apa.html">XDG +menu spec</a></dd> +<dt>DocWeight</dt> +<dd>The "weighting" given to documents. Documents with higher +DocWeight are shown below documents with lower DocWeights. This +should generally not be used without a good reason</dd> +<dt><strong>DocIdentifier</strong></dt> +<dd>The DocIdentifier is a reverse-DNS identifier used to determine +whether two documents describe the same subject. The general form of +the DocIdentifier is "org.<organisation>.<subject>". The "org." +should be substituted for "com." for commercial programs. Please +choose the <organisation> appropriately.</dd> +<dt>DocLang</dt> +<dd>When the meta-data file describes a single language, but not the +"C" locale, this field gives the language. This is used for (e.g.) +distributing language packs.</dd> +</dl> + +<p><strong>TODO</strong>: Describe children element and where they are useful</p> + +<h3>Additional Fields</h3> +<p>There are several fields that should not be used except in specific +circumstances. These are described here.</p> + +<dl> +<dt>x-DocHeritage</dt> +<dd>This is used when moving from scrollkeeper. The scrollkeeper +translation utilities form a new-style identifier of the form +"org.scrollkeeper.<scrollkeeper-seriesid>". In order to ensure +your new document is picked up in it's place, you must specify this +field in the form of: <p>x-DocHeritage=org.scrollkeeper.<seriesid></p> +</dd> +<dt>x-Scrollkeeper-omf-loc</dt> +<dd>This should never be used. It is used by the scrollkeeper +compatibility to provide the location of the scrollkeeper omf files.</dd> +</dl> + +<h2>Making your meta-data files accessible</h2> +<p>By default, Rarian will pick up meta-data files found in the "help" +subdirectory of the XDG_DATA_DIRS environment variable. If this +environment variable is not set, Rarian will default to checking in +/usr/share/help and /usr/local/share/help.</p> + +<p>In addition, the environment variable XDG_DATA_HOME can also be +used to provide user-specific files. Rarian will check +$XDG_DATA_HOME/.share/help. If XDG_DATA_HOME is not set, it defaults +to $HOME.</p> + +<p>To be picked up by Rarian, the meta-data file must be placed in one +of these directories (or a sub-directory thereof). The only other +requisite for documents is that the meta-data file must have the +suffix ".document". For example, the example file presented above +would be named "beanstalk.document".</p> + +<h3>Accessing your documentation</h3> + +<p><strong>Note:</strong> This section is due for heavy revision once +several things come together. It is aimed at GNOME documentation +currently. Once the XDG help spec is implemented / supported, this +will become obsolete</p> + +<p>Having written your documentation, copied your meta-data file +to the correct location, you now have several options to access your +documentation from your application:</p> +<ul> +<li>Use libgnome-provided help functions.</li> +<li>Call "yelp" from the command line, with the parameter +"ghelp:>name of meta-data file<". I.e. to load the beanstalk +document, the command line would be: "yelp ghelp:beanstalk".</li> +</ul> + +<p><strong>Note:</strong> libgnome currently uses a different method +for determining the location and name of a file to be opened within +yelp. This may require some playing around with. We are actively +working to make this obsolete and rely more on the DocIdentifier.</p> + +</body> +</html>
\ No newline at end of file diff --git a/docs/rar-skcompat.xhtml b/docs/rar-skcompat.xhtml new file mode 100644 index 0000000..ac6de18 --- /dev/null +++ b/docs/rar-skcompat.xhtml @@ -0,0 +1,147 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE html +PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<title>Rarian Scrollkeeper Compatibility</title> +</head> +<body> +<p><a href="index.xhtml">return to index</a></p> + +<h1>Rarian Scrollkeeper Compatibility</h1> + +<p>In addition to its new (and better) meta-data format, Rarian also +provides backwards compatibility for scrollkeeper. This section +outlines the basics of scrollkeeper files and how to use them. Don't +expect too much though.</p> + +<p><strong>Note</strong>: If you are using GNOME, it is strongly +recommended that you use <em>gnome-doc-utils</em>, which is described +on <a +href="http://live.gnome.org/GnomeDocUtilsCreateNew">live.gnome.org</a>.</p> + +<h2>Scrollkeeper Meta-data files</h2> + +<p>Scrollkeeper uses <em>omf</em> files, which are XML based. The +main text elements that are of interest are:</p> +<dl> +<dt>title</dt> +<dd>The title of the document</dd> +<dt>description</dt> +<dd>The description of the document (the blurb that appears in table +of contents)</dd> +<dt>creator</dt> +<dd>The creator of the documentation</dd> +<dt>maintainer</dt> +<dd>The person that currently looks after the documentation</dd> +<dt>type</dt> +<dd>The type of the documentation ("user's guide" etc.)</dd> +<dt>date</dt> +<dd>The last revision date of the documentation</dd> +</dl> + +<p>Other fields that have attributes:</p> +<dl> +<dt><em>node</em></dt> +<dd><em>attributes</em>: what is does</dd> +<dt>version</dt> +<dd>identifier: Who knows?,<em> date</em>: As the date field</dd> +<dt>subject</dt> +<dd><em>category</em>: Which category the document belongs to. A list of +categories can be found on <a +href="http://scrollkeeper.sourceforge.net/documentation/categories.html"> +the scrollkeeper website</a></dd> +<dt>format</dt> +<dd><em>mime</em>: the mime type of the document, <em>dtd</em>: the dtd of the document +(like "-//OASIS//DTD DocBook XML V4.3//EN")</dd> +<dt>identifier</dt> +<dd><em>url</em>: The URI of the actual documentation (bet you were wondering +where that was, weren't you?)</dd> +<dt>language</dt> +<dd><em>code</em>: The language code describing the language the document +described by the meta-data is in..</dd> +<dt>relation</dt> +<dd><em>seriesid</em>: The unique scrollkeeper seriesid. Can be generated +using the <em>scrollkeeper-gen-seriesid</em> program.</dd> +<dt>rights</dt> +<dd><em>type</em>: The license the documentation is available under, +<em>license.version</em>: The specific version of the license, <em>holder</em>: Who +actually holds the license.</dd> +</dl> + +<h2>Example scrollkeeper file</h2> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<omf> + <resource> + <creator>The Professor <theprof@example.com></creator> + <maintainer>The Professor <theprof@example.com></maintainer> + <title>The Beanstalk User Guide</title> + <date>June 2021</date> + <version identifier="The Beanstalk User Guide v1.0" date="June 2021"/> + <subject category="GNOME|Desktop"/> + <description> + Beanstalks are big and may, if you're very, very lucky, lead to + golden eggs. + </description> + <type>user's guide</type> + <format mime="application/xhtml+xml" dtd="-//W3C//DTD XHTML 1.0 Strict//EN"/> + <identifier url="beanstalk.xhtml"/> + <language code="C"/> + <relation seriesid="ceae33be-2a60-11dc-9e02-e1e3ec1cb44f"/> + <rights type="GNU FDL" license.version="1.1" holder="The Professor"/> + </resource> +</omf> +</pre> + +<p>Basically, it's easier to copy this example and modify it to suit +your needs than to try and write your own.</p> + +<p>Normally, the name of your omf files (after installation) should +be <package name>-<langcode>.omf. Before installation, +you can name it whatever you want. However, I'd recommend:</p> +<pre><package name>-<langcode>.omf.in</pre> + +<p>So for the beanstalk example, the distributed file (in source +archives, i.e. to allow people to install it anywhere) would be:</p> +<pre>beanstalk-C.omf.in</pre> + +<p>Which is then converted using <em>scrollkeeper-preinstall</em>, +described below.</p> + +<h2>Installing documentation</h2> + +<p>Scrollkeeper installation is a little ... quirky. First, copy +your actual documentation to where you want. To install the +meta-data, fist run <em>scrollkeeper-preinstall</em> using the +arguments like:</p> +<pre>scrollkeeper-preinstall <installed doc name> <current omf name> <new omf name></pre> + +<p>For example, for the beanstalk manual, this might look like:</p> + +<pre>scrollkeeper-preinstall /usr/share/beanstalk/manual/C/beanstalk.xhtml beanstalk-pre-C.omf beanstalk-C.omf</pre> + +<p>After that, you can now copy the newly generated omf file into +<prefix>/share/omf/<name>/ where <name> is generally +the name of your package. Repeat this procedure for each language.</p> + +<p>Afterward, you can now run <em>scrollkeeper-update</em>. This has +a few options you must specify to get the correct behaviour. This +will need some tweaking, but in general:</p> + +<pre>scrollkeeper-update -o <prefix>/share/omf</pre> + +<p>Should get you reasonably close. (If using Rarian, this will be +sufficient).</p> + +<p>And that's it. You'll probably want to put this stuff in your +makefiles. I have no idea how to do all this. I'd recommend looking +for other packages that use scrollkeeper and adapt their stuff. (It's +like the old autoconf joke - only 2 people have ever written a +configure.in, everyone else just copies them)</p> + +</body> +</html> + diff --git a/docs/rarian.document.in b/docs/rarian.document.in new file mode 100644 index 0000000..4709e09 --- /dev/null +++ b/docs/rarian.document.in @@ -0,0 +1,8 @@ +# Rarian meta-data +[Document] +Name=Rarian Reference Manual +Comment=Rarian is a documentation meta-data library. This describes how to write documentation accessible to it and how to use the library. +DocIdentifier=org.other.rarian +Categories=Development|Libraries +DocPath=@datarootdir@/librarian/manual/index.xhtml +DocType=application/xhtml+xml |