documentation update to mention bibliography

4 files changed, 390 insertions, 13 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
diff --git a/data/doc/sisu/CHANGELOG_v6 b/data/doc/sisu/CHANGELOG_v6
index 06eb3618..26958d81 100644
--- a/data/doc/sisu/CHANGELOG_v6
+++ b/data/doc/sisu/CHANGELOG_v6
@@ -138,6 +138,8 @@ http://www.jus.uio.no/sisu/pkg/src/sisu_6.4.0.orig.tar.xz
     or:
     * tag footnote citations that should appear in the bibliography
 
+  * documentation, update to mention bibliography
+
 ** SiSU "UnFrozen" - prior to end of Debian Freeze
   (upstream bugfix 6.3.2 (5.7.2) intended for Jessie (packaged for Debian as
   5.7.1-2) was not accepted)
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 }
 
diff --git a/man/man1/sisu.1 b/man/man1/sisu.1
index e0f63624..ee8890c9 100644
--- a/man/man1/sisu.1
+++ b/man/man1/sisu.1
@@ -2373,6 +2373,148 @@ page (break) line across page (dividing paragraphs):
 -..-
 .fi
 
+.SH BIBLIOGRAPHY / REFERENCES
+
+
+.BR
+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.
+
+.BR
+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:
+.nf
+1~biblio Bibliography
+.fi
+
+.SH A MARKUP TAGGED METADATA BIBLIOGRAPHY SECTION
+
+
+.BR
+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.
+
+.BR
+The required tags are au: ti: and year: [^10] an short quick example might be
+as follows:
+.nf
+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
+.fi
+
+
+.BR
+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.
+
+.BR
+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:
+
+.BR
+  number, author (firstname & initials, surname), fulltitle, publisher, year,
+  url (if any)
+
+.BR
+and for articles:
+
+.BR
+  number, author (firstname & initials, surname), title, journal, volume, year,
+  url (if any)
+
+.BR
+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.
+.nf
+The following footnote~{ quixote1605, pp 1000 - 1001, also Benkler2006 p 1. }~
+.fi
+
+
+.BR
+would be presented as:
+
+.BR
+Quixote and Panza,
+.I Taming Windmills
+(1605), pp 1000 - 1001 also, Benkler,
+.I Wealth of Networks,
+(2006) p 1 or rather[^11]
+.SH TAGGING CITATIONS FOR INCLUSION IN THE BIBLIOGRAPHY
+
+
+.BR
+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)
+
+.BR
+Here you would write something like the following, either in regular text or a
+footnote
+.nf
+See .: Quixote, Don; Panza, Sancho /{Taming Windmills, Keeping True}/ (1605) :.
+.fi
+
+
+.BR
+
+.B 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.
 .SH BOOK INDEX
 
 
@@ -2582,7 +2724,7 @@ contain other documents.
 
 .BR
 Note: a secondary file of the composite document is built prior to processing
-with the same prefix and the suffix ._sst [^10]
+with the same prefix and the suffix ._sst [^12]
 .SH SISU INSERT FILES (.SSI)
 
 
@@ -2782,7 +2924,7 @@ The default homepage may use homepage.css or html. css
 
 .BR
 Under consideration is to permit the placement of a CSS file with a different
-name in directory _sisu/css directory or equivalent.[^11]
+name in directory _sisu/css directory or equivalent.[^13]
 .SH ORGANISING CONTENT - DIRECTORY STRUCTURE AND MAPPING
 
 
@@ -3281,9 +3423,9 @@ formats.
 .B SiSU
 feeds sisu markupd documents into sql type databases
 .I PostgreSQL
-[^12] and/or
+[^14] and/or
 .I SQLite
-[^13] database together with information related to document structure.
+[^15] database together with information related to document structure.
 
 .BR
 This is one of the more interesting output forms, as all the structural data of
@@ -3553,10 +3695,10 @@ INCLUDING OBJECT CITATION NUMBERING (BACKEND CURRENTLY POSTGRESQL)
 
 
 .BR
-Sample search frontend <http://search.sisudoc.org> [^14] A small database and
+Sample search frontend <http://search.sisudoc.org> [^16] A small database and
 sample query front-end (search from) that makes use of the citation system, .I
 object citation numbering
-to demonstrates functionality.[^15]
+to demonstrates functionality.[^17]
 
 .BR
 
@@ -3581,7 +3723,7 @@ documents matched.
 Note you may set results either for documents matched and object number
 locations within each matched document meeting the search criteria; or display
 the names of the documents matched along with the objects (paragraphs) that
-meet the search criteria.[^16]
+meet the search criteria.[^18]
 .TP
 .B sisu -F --webserv-webrick
 builds a cgi web search frontend for the database created
@@ -3971,6 +4113,16 @@ Table from the Wealth of Networks by Yochai Benkler
 .BR
 .TP
 .BI 10.
+for which you may alternatively use the full form author: title: and year:
+
+.BR
+.TP
+.BI 11.
+Quixote and Panza, Taming Windmills (1605), pp 1000 - 1001 also, Benkler, Wealth of Networks (2006), p 1
+
+.BR
+.TP
+.BI 12.
 \.ssc (for composite) is under consideration but \._sst makes clear that this
 is not a regular file to be worked on, and thus less likely that people will
 have "accidents", working on a \.ssc file that is overwritten by subsequent
@@ -3979,37 +4131,37 @@ appropriate suffix to use.
 
 .BR
 .TP
-.BI 11.
+.BI 13.
 SiSU has worked this way in the past, though this was dropped as it was
 thought the complexity outweighed the flexibility, however, the balance was
 rather fine and this behaviour could be reinstated.
 
 .BR
 .TP
-.BI 12.
+.BI 14.
 <http://www.postgresql.org/> <http://advocacy.postgresql.org/>
 <http://en.wikipedia.org/wiki/Postgresql>
 
 .BR
 .TP
-.BI 13.
+.BI 15.
 <http://www.hwaci.com/sw/sqlite/> <http://en.wikipedia.org/wiki/Sqlite>
 
 .BR
 .TP
-.BI 14.
+.BI 16.
 <http://search.sisudoc.org>
 
 .BR
 .TP
-.BI 15.
+.BI 17.
 (which could be extended further with current back-end). As regards scaling
 of the database, it is as scalable as the database (here Postgresql) and
 hardware allow.
 
 .BR
 .TP
-.BI 16.
+.BI 18.
 of this feature when demonstrated to an IBM software innovations evaluator
 in 2004 he said to paraphrase: this could be of interest to us. We have large
 document management systems, you can search hundreds of thousands of documents