From 1d239f2504dffc05c39efd38a10a27dba9e9c85e Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Sun, 26 Jun 2011 21:26:07 -0400 Subject: v3: documentation, on additional breaks in document, (remove some old info) * linebreak \\ (previously undocumented
kept but depreciated) [it is intended that this should close #617298 (post mail)] * page break (breaks column if column, else breaks page) * page new (new page, breaks page) * sisurc.yml set output directory structure by language * removed section on hyperestraier, too specialised for general manpage (also section not checked recently) --- man/man1/sisu.1 | 255 +++++++++++++++++++++----------------------------------- 1 file changed, 94 insertions(+), 161 deletions(-) (limited to 'man/man1') diff --git a/man/man1/sisu.1 b/man/man1/sisu.1 index c152d5eb..2994ef64 100644 --- a/man/man1/sisu.1 +++ b/man/man1/sisu.1 @@ -1,4 +1,4 @@ -.TH "sisu" "1" "2011\-04\-17" "3.0.7\-beta\-rb1.9.2p180" "SiSU" +.TH "sisu" "1" "2011-06-24" "3.0.13-beta-rb1.9.2p180" "SiSU" .br .SH NAME .br @@ -174,8 +174,7 @@ system to reliably reference its documents. works well in a complementary manner with such collaborative technologies as Wikis, which can take advantage of and be used to discuss the substance of content prepared in -.B SiSU -. +.B SiSU. .br @@ -1266,12 +1265,9 @@ normally be marked 1.1.1 or 1.1.2 or 1.2.1 or 2.1.1 etc. in a document .br normal text, -.B emphasis -, -.B bold text -, -.I italics -, +.B emphasis, +.B bold text, +.I italics, .I underscore , "citation", ^superscript^, [subscript], ++inserted text++, \-\-strikethrough\-\-, monospace @@ -2098,7 +2094,53 @@ tag code{# as demonstrated here: 44 | death."' .fi -.SH 9.7 BOOK INDEX +.SH 9.7 ADDITIONAL BREAKS \- LINEBREAKS WITHIN OBJECTS, COLUMN AND PAGE\-BREAKS + +.SH 9.7.1 LINE\-BREAKS + +.br +To break a line within a "paragraph object", two backslashes \e\e +with a space before and a space or newline after them +may be used. + +.nf + To break a line within a "paragraph object", + two backslashes \e\e with a space before + and a space or newline after them \e\e + may be used. +.fi + +.br +The html break br enclosed in angle brackets (though undocumented) is available +in versions prior to 3.0.13 and 2.9.7 (it remains available for the time being, +but is depreciated). + +.SH 9.7.2 PAGE BREAKS + +.br +Page breaks are only relevant and honored in some output formats. A page break +or a new page may be inserted manually using the following markup on a line on +its own: + +.nf + <:pb> +.fi + +.br +or + +.nf + <:pn> +.fi + +.br +page new <:pn> breaks the page, starts a new page. + +.br +page break <:pb> breaks a column, starts a new column, if using columns, else +breaks the page, starts a new page. + +.SH 9.8 BOOK INDEX .br To make an index append to paragraph the book index term relates to it, using @@ -2945,8 +2987,8 @@ appearance. .B SiSU is about the ability to auto\-generate documents. Home pages are regarded as custom built items, and are not created by -.B SiSU -. More accurately, +.B SiSU. +More accurately, .B SiSU has a default home page, which will not be appropriate for use with other sites, and the means to provide your own home page instead in one of two ways @@ -3357,125 +3399,16 @@ installed The generated search form must be copied manually to the webserver directory as instructed -.SH 25. HYPERESTRAIER -.br - -.br -See the documentation for hyperestraier: - -.br - - -.br - /usr/share/doc/hyperestraier/index.html - -.br - man estcmd - -.br -NOTE: the examples that follow assume that sisu output is placed in the -directory /home/ralph/sisu_www - -.br -(A) to generate the index within the webserver directory to be indexed: - -.br - estcmd gather \-sd [index \ name] [directory \ path \ to \ index] - -.br -the following are examples that will need to be tailored according to your -needs: - -.br - cd /home/ralph/sisu_www - -.br - estcmd gather \-sd casket /home/ralph/sisu_www - -.br -you may use the 'find' command together with 'egrep' to limit indexing to -particular document collection directories within the web server directory: - -.br - find /home/ralph/sisu_www \-type f | egrep - '/home/ralph/sisu_www/sisu/.+?.html$' |estcmd gather \-sd casket \- - -.br -Check which directories in the webserver/output directory (~/sisu_www or -elsewhere depending on configuration) you wish to include in the search index. - -.br -As sisu duplicates output in multiple file formats, it it is probably -preferable to limit the estraier index to html output, and as it may also be -desirable to exclude files 'plain.txt', 'toc.html' and 'concordance.html', as -these duplicate information held in other html output e.g. - -.br - find /home/ralph/sisu_www \-type f | egrep - '/sisu_www/(sisu|bookmarks)/.+?.html$' | egrep \-v '(doc|concordance).html$' - |estcmd gather \-sd casket \- - -.br -from your current document preparation/markup directory, you would construct a -rune along the following lines: - -.br - find /home/ralph/sisu_www \-type f | egrep '/home/ralph/sisu_www/([specify \ - first \ directory \ for \ inclusion]|[specify \ second \ directory \ for \ - inclusion]|[another \ directory \ for \ inclusion? \ \...])/.+?.html$' | - egrep \-v '(doc|concordance).html$' |estcmd gather \-sd - /home/ralph/sisu_www/casket \- - -.br -(B) to set up the search form - +.SH 25. SISU_WEBRICK .br -(i) copy estseek.cgi to your cgi directory and set file permissions to 755: -.br - sudo cp \-vi /usr/lib/estraier/estseek.cgi /usr/lib/cgi\-bin - -.br - sudo chmod \-v 755 /usr/lib/cgi\-bin/estseek.cgi - -.br - sudo cp \-v /usr/share/hyperestraier/estseek.* /usr/lib/cgi\-bin - -.br - [see \ estraier \ documentation \ for \ paths] - -.br -(ii) edit estseek.conf, with attention to the lines starting 'indexname:' and -'replace:': - -.br - indexname: /home/ralph/sisu_www/casket - -.br - replace: ^file:///home/ralph/sisu_www{{!}}http://localhost - -.br - replace: /index.html?${{!}}/ - -.br -(C) to test using webrick, start webrick: - -.br - sisu \-W - -.br -and try open the url: - -.SH 26. SISU_WEBRICK -.br - -.SH 26.1 NAME +.SH 25.1 NAME .br .B SiSU \- Structured information, Serialized Units \- a document publishing system -.SH 26.2 SYNOPSIS +.SH 25.2 SYNOPSIS .br sisu_webrick [port] @@ -3486,7 +3419,7 @@ or .br sisu \-W [port] -.SH 26.3 DESCRIPTION +.SH 25.3 DESCRIPTION .br sisu_webrick is part of @@ -3504,7 +3437,7 @@ The default port for sisu_webrick is set to 8081, this may be modified in the yaml file: ~/.sisu/sisurc.yml a sample of which is provided as /etc/sisu/sisurc.yml (or in the equivalent directory on your system). -.SH 26.4 SUMMARY OF MAN PAGE +.SH 25.4 SUMMARY OF MAN PAGE .br sisu_webrick, may be started on it's own with the command: sisu_webrick [port] @@ -3513,7 +3446,7 @@ or using the sisu command with the \-W flag: sisu \-W [port] .br where no port is given and settings are unchanged the default port is 8081 -.SH 26.5 DOCUMENT PROCESSING COMMAND FLAGS +.SH 25.5 DOCUMENT PROCESSING COMMAND FLAGS .br sisu \-W [port] starts @@ -3523,7 +3456,7 @@ Webrick web\-server, serving output directories, on the port provided, or if no port is provided and the defaults have not been changed in ~/.sisu/sisurc.yaml then on port 8081 -.SH 26.6 FURTHER INFORMATION +.SH 25.6 FURTHER INFORMATION .br For more information on @@ -3533,12 +3466,12 @@ see: or .br or man sisu -.SH 26.7 AUTHOR +.SH 25.7 AUTHOR .br Ralph Amissah or -.SH 26.8 SEE ALSO +.SH 25.8 SEE ALSO .br sisu(1) @@ -3546,7 +3479,7 @@ Ralph Amissah or .br sisu_vim(7) -.SH 27. REMOTE SOURCE DOCUMENTS +.SH 26. REMOTE SOURCE DOCUMENTS .br .br @@ -3607,7 +3540,7 @@ desired document. .SH REMOTE DOCUMENT OUTPUT .br -.SH 28. REMOTE OUTPUT +.SH 27. REMOTE OUTPUT .br .br @@ -3626,7 +3559,7 @@ be used in conjunction with other processing flags, e.g. sisu \-3R sisu_remote.sst .fi -.SH 28.1 COMMANDS +.SH 27.1 COMMANDS .TP .B \-R [filename/wildcard] @@ -3643,12 +3576,12 @@ copies sisu output files to remote host using scp. This requires that sisurc.yml has been provided with information on hostname and username, and that you have your "keys" and ssh agent in place. Also see \-R -.SH 28.2 CONFIGURATION +.SH 27.2 CONFIGURATION .br [expand \ on \ the \ setting \ up \ of \ an \ ssh\-agent \ / \ keychain] -.SH 29. REMOTE SERVERS +.SH 28. REMOTE SERVERS .br .br @@ -3661,10 +3594,10 @@ the program and all documents can just as easily be on a remote server, to which you are logged on using a terminal, and commands and operations would be pretty much the same as they would be on your local machine. -.SH 30. QUICKSTART \- GETTING STARTED HOWTO +.SH 29. QUICKSTART \- GETTING STARTED HOWTO .br -.SH 30.1 INSTALLATION +.SH 29.1 INSTALLATION .br Installation is currently most straightforward and tested on the @@ -3672,7 +3605,7 @@ Installation is currently most straightforward and tested on the platform, as there are packages for the installation of sisu and all requirements for what it does. -.SH 30.1.1 DEBIAN INSTALLATION +.SH 29.1.1 DEBIAN INSTALLATION .br .B SiSU @@ -3736,7 +3669,7 @@ Note however that it is not necessary to install sisu\-complete if not all components of sisu are to be used. Installing just the package sisu will provide basic functionality. -.SH 30.1.2 RPM INSTALLATION +.SH 29.1.2 RPM INSTALLATION .br RPMs are provided though untested, they are prepared by running alien against @@ -3754,7 +3687,7 @@ as root type: .br rpm \-i [rpm \ package \ name] -.SH 30.1.3 INSTALLATION FROM SOURCE +.SH 29.1.3 INSTALLATION FROM SOURCE .br To install @@ -3779,8 +3712,8 @@ first steps are the same, download and unpack the source file: For basic use .B SiSU is only dependent on the programming language in which it is written -.B Ruby -, and +.B Ruby, +and .B SiSU will be able to generate html, EPUB, various XMLs, including ODF (and will also produce LaTeX). Dependencies required for further actions, though it @@ -3861,7 +3794,7 @@ For a list of alternative actions you may type: .br ruby install \-T -.SH 30.2 TESTING SISU, GENERATING OUTPUT +.SH 29.2 TESTING SISU, GENERATING OUTPUT .br To check which version of sisu is installed: @@ -3888,7 +3821,7 @@ change directory to the appropriate one: .br cd /usr/share/doc/sisu/markup\-samples/samples -.SH 30.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF, EPUB +.SH 29.2.1 BASIC TEXT, PLAINTEXT, HTML, XML, ODF, EPUB .br Having moved to the directory that contains the markup samples (see @@ -3901,7 +3834,7 @@ sisu \-NhwoabxXyv free_as_in_freedom.rms_and_free_software.sam_williams.sst this will generate html including a concordance file, opendocument text format, plaintext, XHTML and various forms of XML, and OpenDocument text -.SH 30.2.2 LATEX / PDF +.SH 29.2.2 LATEX / PDF .br Assuming a LaTeX engine such as tetex or texlive is installed with the required @@ -3924,7 +3857,7 @@ should generate most available output formats: html including a concordance file, opendocument text format, plaintext, XHTML and various forms of XML, and OpenDocument text and pdf -.SH 30.2.3 RELATIONAL DATABASE \- POSTGRESQL, SQLITE +.SH 29.2.3 RELATIONAL DATABASE \- POSTGRESQL, SQLITE .br Relational databases need some setting up \- you must have permission to create @@ -3947,9 +3880,9 @@ sisu \-\-pgsql \-\-recreate sisu \-\-pgsql \-v \-\-import free_as_in_freedom.rms_and_free_software.sam_williams.sst -.SH 30.3 GETTING HELP +.SH 29.3 GETTING HELP -.SH 30.3.1 THE MAN PAGES +.SH 29.3.1 THE MAN PAGES .br Type: @@ -3970,7 +3903,7 @@ as within the package itself: .br * man directory [^27] -.SH 30.3.2 BUILT IN HELP +.SH 29.3.2 BUILT IN HELP .br sisu \-\-help @@ -3984,7 +3917,7 @@ sisu \-\-help \-\-commands .br sisu \-\-help \-\-markup -.SH 30.3.3 THE HOME PAGE +.SH 29.3.3 THE HOME PAGE .br @@ -3995,7 +3928,7 @@ sisu \-\-help \-\-markup .br -.SH 30.4 MARKUP SAMPLES +.SH 29.4 MARKUP SAMPLES .br A number of markup samples (along with output) are available off: @@ -4016,7 +3949,7 @@ they are available in non\-free[^28] to include them it is necessary to include non\-free in your /etc/apt/source.list or obtain them from the sisu home site. -.SH 31. EDITOR FILES, SYNTAX HIGHLIGHTING +.SH 30. EDITOR FILES, SYNTAX HIGHLIGHTING .br .br @@ -4198,7 +4131,7 @@ NOTE: but, \ display \ linewrap \ (without \ line\-breaks) \ is \ a \ convenient \ editor \ feature \ to \ have \ for \ sisu \ markup] -.SH 32. HOW DOES SISU WORK? +.SH 31. HOW DOES SISU WORK? .br .br @@ -4222,7 +4155,7 @@ document layout, publishing, content certification, concordance etc.), and makes it possible to take advantage of some of the strengths of established ways of representing documents, (or indeed to create new ones). -.SH 33. SUMMARY OF FEATURES +.SH 32. SUMMARY OF FEATURES .br .br @@ -4382,10 +4315,10 @@ present. For example objects could be saved individually and identified by their hashes, with an index of how the objects relate to each other to form a document. -.SH 34. HELP SOURCES +.SH 33. HELP SOURCES .br -.SH 34.1 MAN PAGES +.SH 33.1 MAN PAGES .br man sisu @@ -4441,7 +4374,7 @@ document. .br man sisu_webrick -.SH 34.2 SISU GENERATED OUTPUT \- LINKS TO HTML +.SH 33.2 SISU GENERATED OUTPUT \- LINKS TO HTML .br Note @@ -4451,7 +4384,7 @@ documentation is prepared in and output is available in multiple formats including amongst others html, pdf, odf and epub, which may be also be accessed via the html pages[^29] -.SH 34.2.1 WWW.SISUDOC.ORG +.SH 33.2.1 WWW.SISUDOC.ORG .br @@ -4459,9 +4392,9 @@ pdf, odf and epub, which may be also be accessed via the html pages[^29] .br -.SH 34.3 MAN2HTML +.SH 33.3 MAN2HTML -.SH 34.3.1 LOCALLY INSTALLED +.SH 33.3.1 LOCALLY INSTALLED .br file:///usr/share/doc/sisu/html/sisu.1.html @@ -4481,7 +4414,7 @@ file:///usr/share/doc/sisu/html/sisu.1.html .br /usr/share/doc/sisu/html/sisu_webrick.1.html -.SH 34.3.2 WWW.jus.uio.no/sisu +.SH 33.3.2 WWW.JUS.UIO.NO/SISU .br -- cgit v1.2.3