diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 199 |
1 files changed, 187 insertions, 12 deletions
@@ -37,15 +37,20 @@ Homepages: INSTALL OR RUN WITHOUT INSTALLATION *********************************** -SOURCE TARBALL --------------- +SOURCE TREE +----------- RUN OFF SOURCE PACKAGE DIRECTORY TREE (WITHOUT INSTALLING) .......................................................... -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: + +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 @@ -55,14 +60,36 @@ 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. -GEM INSTALL (WITH RAKE) -....................... +GEM INSTALL +........... Gem install, you need to: (i) create the gemspec; (ii) build the gem (from the gemspec); (iii) install the gem + +---------------------------------------- + +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: + + qi gem --create --build --install --stable + +or + + qi gem --create --build --install --unstable + + +---------------------------------------- + +GEM INSTALL WITH RAKE +..................... + Provided you have ruby & rake, this can be done with the single command: rake gem_create_build_install # (to build and install sisu v5 & sisu v6, @@ -79,7 +106,21 @@ separate gems are made/installed for sisu v5 & sisu v6 contained in source: for individual steps (create, build, install) see rake options, rake -T to specify sisu version for sisu installed via gem - gem search sisu +For a list of alternative actions you may type: + + rake help + + rake -T + +Rake: <http://rake.rubyforge.org/> <http://rubyforge.org/frs/?group_id=50> + + +---------------------------------------- + +MISC GEM +........ + +gem search sisu sisu _5.6.2_ --version @@ -89,15 +130,21 @@ to uninstall sisu installed via gem sudo gem uninstall --verbose sisu -For a list of alternative actions you may type: +DIRECT INSTALLATION WITH QI (QUICK INSTALL) SCRIPT +.................................................. - rake help +(This requires that ruby -thor is installed). - rake -T +Root will be requested as required: -Rake: <http://rake.rubyforge.org/> <http://rubyforge.org/frs/?group_id=50> + qi setup --bin --lib --conf --data --share --man -Rant: <http://make.rubyforge.org/> <http://rubyforge.org/frs/?group_id=615> +or + + qi setup --all + +You may wish to do a dryrun to see where files would be installed without +copying them, to do so add the flag --dryrun INSTALLATION WITH SETUP.RB .......................... @@ -2048,6 +2095,129 @@ page (break) line across page (dividing paragraphs): -..- +BIBLIOGRAPHY / REFERENCES +......................... + +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: + +1~biblio Bibliography + + +---------------------------------------- + +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: [^10] an short quick example might be +as follows: + +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 + +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: + + number, author (firstname & initials, surname), fulltitle, publisher, year, + url (if any) + +and for articles: + + 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. + +The following footnote~{ quixote1605, pp 1000 - 1001, also Benkler2006 p 1. }~ + +would be presented as: + +Quixote and Panza, /Taming Windmills/ (1605), pp 1000 - 1001 also, Benkler, +/Wealth of Networks/, (2006) p 1 or rather[^11] + + +---------------------------------------- + +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 + +See .: Quixote, Don; Panza, Sancho /{Taming Windmills, Keeping True}/ (1605) :. + +*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. + BOOK INDEX .......... @@ -2179,3 +2349,8 @@ Configure substitution in _sisu/sisu_document_make [9]: Table from the Wealth of Networks by Yochai Benkler <http://www.jus.uio.no/sisu/the_wealth_of_networks.yochai_benkler> + + [10]: for which you may alternatively use the full form author: title: and year: + + [11]: Quixote and Panza, /Taming Windmills/ (1605), pp 1000 - 1001 also, Benkler, + /Wealth of Networks/ (2006), p 1 |