diff options
Diffstat (limited to 'data/doc/sisu/markup-samples/manual/en')
3 files changed, 144 insertions, 13 deletions
diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_download.ssi b/data/doc/sisu/markup-samples/manual/en/sisu_download.ssi index 085229f1..c5f31d2a 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_download.ssi +++ b/data/doc/sisu/markup-samples/manual/en/sisu_download.ssi @@ -44,13 +44,15 @@ For changelogs see http://www.jus.uio.no/sisu/SiSU/changelog.html Git repository currently at: -_* git clone git://git.sisudoc.org/git/code/sisu.git - -_* git clone _http://git.sisudoc.org/git/code/sisu.git +_* git clone git://git.sisudoc.org/git/code/sisu.git --branch upstream _* http://git.sisudoc.org/gitweb/?p=code/sisu.git;a=summary -On using git, see +To get the most recent source without repo history: + +_* git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream + +On using git, see: !_ Git documentation: {~^ Git User's Manual }http://www.kernel.org/pub/software/scm/git/docs/user-manual.html, {~^ Everyday GIT With 20 Commands Or So }http://www.kernel.org/pub/software/scm/git/docs/everyday.html, {~^ A tutorial introduction to git }http://www.kernel.org/pub/software/scm/git/docs/v1.4.4.4/tutorial.html, {~^ A tutorial introduction to git: part two }http://www.kernel.org/pub/software/scm/git/docs/v1.4.4.4/tutorial-2.html diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_install_run.sst b/data/doc/sisu/markup-samples/manual/en/sisu_install_run.sst index 08c9ba02..97fdbd28 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_install_run.sst +++ b/data/doc/sisu/markup-samples/manual/en/sisu_install_run.sst @@ -19,26 +19,46 @@ :A~? SiSU Installation notes -1~source_tarball Source tarball +1~source_tree Source tree 2~ run off source package directory tree (without installing) ={ SiSU program:run off source package directory tree;SiSU:run off source package directory tree } -1. Download the latest source +Download & unpack the latest source tarball -2. Unpack the source +or + +Git clone the latest source, to clone the latest source without the repo history: + +``` code +git clone --depth 1 git://git.sisudoc.org/git/code/sisu.git --branch upstream +``` Provided you have Ruby, SiSU can be run without installation straight from the source package directory tree. Run ruby against the full path to bin/sisu (in the unzipped source package directory tree) Note however, that additional external package dependencies, such as texlive (for pdfs), sqlite3 or postgresql (for search) should you desire to use them are not taken care of for you. -2~ Gem install (with rake) +2~ Gem install ={ SiSU program:gem;SiSU:ruby gem } Gem install, you need to: (i) create the gemspec; (ii) build the gem (from the gemspec); (iii) install the gem +3~ Gem install with qi (quick install) script + +(This requires that ruby-thor is installed). + +qi (quick install) can go through the steps required to install the gem: + +_1 qi gem --create --build --install --stable + +or + +_1 qi gem --create --build --install --unstable + +3~ Gem install with rake + Provided you have ruby & rake, this can be done with the single command: _1 rake gem_create_build_install # (to build and install sisu v5 & sisu v6, alias gemcbi) @@ -52,6 +72,16 @@ _1 rake gem_create_build_install_unstable # (to build and install sisu v6, alias for individual steps (create, build, install) see rake options, rake -T to specify sisu version for sisu installed via gem +For a list of alternative actions you may type: + +_1 rake help + +_1 rake -T + +Rake: http://rake.rubyforge.org/ http://rubyforge.org/frs/?group_id=50 + +3~ misc Gem + gem search sisu _1 sisu _${sisu_stable}_ --version @@ -62,15 +92,19 @@ to uninstall sisu installed via gem _1 sudo gem uninstall --verbose sisu -For a list of alternative actions you may type: +2~ direct installation with qi (quick install) script -_1 rake help +(This requires that ruby-thor is installed). -_1 rake -T +Root will be requested as required: -Rake: http://rake.rubyforge.org/ http://rubyforge.org/frs/?group_id=50 +_1 qi setup --bin --lib --conf --data --share --man + +or + +_1 qi setup --all -Rant: http://make.rubyforge.org/ http://rubyforge.org/frs/?group_id=615 +You may wish to do a dryrun to see where files would be installed without copying them, to do so add the flag --dryrun 2~ installation with setup.rb ={ SiSU program:setup.rb;SiSU:setup.rb } diff --git a/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst b/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst index 3a8ae570..43c161d1 100644 --- a/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst +++ b/data/doc/sisu/markup-samples/manual/en/sisu_markup.sst @@ -1335,6 +1335,101 @@ code{ }code +2~ Bibliography / References +={ SiSU markup:references|bibliography|citations;references;book index } + +There are three ways to prepare a bibliography using sisu: (i) manually preparing and marking up as regular text in sisu a list of references; (ii) (tagging citations for inclusion) using a restricted form for citations and marking them up to identify them as such (which sisu then parses and attempts to build a bibliography from), or; (iii) preparing a bibliography, using metadata tags for author: title: year: and the like, including an id: and shortname: the id can be inserted in footnotes in place of the citation, and it will be substituted there by the short title for the work. + +For the heading/section sequence: endnotes, bibliography then book index to occur, the name biblio or bibliography must be given to the bibliography section, like so: + +code{ + +1~biblio Bibliography + +}code + +3~ a markup tagged metadata bibliography section + +Here instead of writing your full citations directly in footnotes, each time you have new material to cite, you add it to your bibliography section (if it has not been added yet) providing the information you need against an available list of tags. At the time of writing, for articles: au|author; ti|title; lng|language; jo|journal; vo|volume; edr|editor; yr|year; pst|publisher_state; url; note; sn|shortname; id; and \\ for books: au|author; ti|title; st|subtitle; lng|language; pb|publisher; edn|edition; yr|year; pst|publisher_state; url; note; sn|shortname; id. + +The required tags are au: ti: and year: ~{for which you may alternatively use the full form author: title: and year: }~ an short quick example might be as follows: + +code{ + +1~biblio Bibliography + +au: von Hippel, E. +ti: Perspective: User Toolkits for Innovation +lng: (language) +jo: Journal of Product Innovation Management +vo: 18 +edr: (editor) +yr: 2001 +note: +sn: Hippel, /{User Toolkits}/ (2001) +id: vHippel_2001 +% form: + +au: Benkler, Yochai +ti: The Wealth of Networks +st: How Social Production Transforms Markets and Freedom +lng: (language) +pb: Harvard University Press +edn: (edition) +yr: 2006 +pst: U.S. +url: http://cyber.law.harvard.edu/wealth_of_networks/Main_Page +note: +sn: Benkler, /{Wealth of Networks}/ (2006) +id: Benkler2006 + +au: Quixote, Don; Panza, Sancho +ti: Taming Windmills, Keeping True +jo: Imaginary Journal +yr: 1605 +url: https://en.wikipedia.org/wiki/Don_Quixote +note: made up to provide an example of author markup for an article with two authors +sn: Quixote and Panza, /{Taming Windmills}/ (1605) +id: quixote1605 + +}code + +Note that the section name biblio (or bibliography) is required for the bibliography to be recognized as such, parsed correctly, and placed after the auto-generated endnote section. + +Using this method, work goes into preparing the bibliography, which will be automatically sorted by surname and presented, under the References or Bibliography section using the format for books: + +_1 number, author (firstname & initials, surname), fulltitle, publisher, year, url (if any) + +and for articles: + +_1 number, author (firstname & initials, surname), title, journal, volume, year, url (if any) + +The metadata tags may include shortname and id, if provided, every time the given id is found within the text it will be replaced by the given short title of the work (it is for this reason the short title has sisu markup to italicize the title), it should work with any page numbers to be added, the short title should be one that can easily be used to look up the full description in the bibliography. + +code{ + +The following footnote~{ quixote1605, pp 1000 - 1001, also Benkler2006 p 1. }~ + +}code + +would be presented as: + +Quixote and Panza, /{Taming Windmills}/ (1605), pp 1000 - 1001 also, Benkler, /{Wealth of Networks}/, (2006) p 1 or rather~{ Quixote and Panza, /{Taming Windmills}/ (1605), pp 1000 - 1001 also, Benkler, /{Wealth of Networks}/ (2006), p 1 }~ + +3~ Tagging citations for inclusion in the Bibliography + +Here whenever you make a citation that you wish be included in the bibliography, you tag the citation as such using special delimiters (which are subsequently removed from the final text produced by sisu) + +Here you would write something like the following, either in regular text or a footnote + +code{ + +See .: Quixote, Don; Panza, Sancho /{Taming Windmills, Keeping True}/ (1605) :. + +}code + +SiSU will parse for a number of patterns within the delimiters to try make out the authors, title, date etc. and from that create a Bibliography. This is more limited than the previously described method of preparing a tagged bibliography, and using an id within text to identify the work, which also lends itself to greater consistency. + 2~ Book index ={ SiSU markup:book index;book index } |