documentation update to mention bibliography

1 files changed, 128 insertions, 0 deletions

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
 
  <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