From 28203dedfb83ba2d9272b22d73133fc12af5b2ab Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Sun, 22 Mar 2015 14:13:00 -0400 Subject: documentation update to mention bibliography --- README | 128 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) (limited to 'README') diff --git a/README b/README index 51d49f7d..7af7f698 100644 --- a/README +++ b/README @@ -2048,6 +2048,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 +2302,8 @@ Configure substitution in _sisu/sisu_document_make [9]: Table from the Wealth of Networks by 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 -- cgit v1.2.3