summaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorRalph Amissah <ralph@amissah.com>2015-05-12 18:33:52 +0000
committerRalph Amissah <ralph@amissah.com>2015-05-15 04:22:19 +0000
commitab31d70b0d338898fa118697ebf79b3af2ef2355 (patch)
treeb7632b0c1900e5a4befa5de05607f376a5cfb6c3 /README
parentappendices: bibliography & glossary, worked on (diff)
downloadsisu-ab31d70b0d338898fa118697ebf79b3af2ef2355.zip
sisu-ab31d70b0d338898fa118697ebf79b3af2ef2355.tar.xz
documentation update !bibliography & !glossary
Diffstat (limited to 'README')
-rw-r--r--README107
1 files changed, 70 insertions, 37 deletions
diff --git a/README b/README
index d88d13b..8997b7f 100644
--- a/README
+++ b/README
@@ -2080,20 +2080,22 @@ 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.
+There are three ways to prepare a bibliography using sisu (which are mutually
+exclusive): (i) manually preparing and marking up as regular text in sisu a
+list of references, this is treated as a regular document segment (and placed
+before endnotes if any); (ii) preparing a bibliography, marking a heading level
+1~!biblio (note the exclamation mark) and preparing a bibliography using
+various metadata tags including for author: title: year: a list of which is
+provided below, or; (iii) as an assistance in preparing a bibliography, marking
+a heading level 1~!biblio and tagging citations within footnotes for inclusion,
+identifying citations and having a parser attempt to extract them and build a
+bibliography of the citations provided.
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
+1~!biblio
----------------------------------------
@@ -2104,23 +2106,19 @@ 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.
+list of tags (provided below).
The required tags are au: ti: and year: [^10] an short quick example might be
as follows:
-1~biblio Bibliography
+1~!biblio
au: von Hippel, E.
ti: Perspective: User Toolkits for Innovation
lng: (language)
jo: Journal of Product Innovation Management
vo: 18
-edr: (editor)
+ed: (editor)
yr: 2001
note:
sn: Hippel, /{User Toolkits}/ (2001)
@@ -2134,7 +2132,7 @@ lng: (language)
pb: Harvard University Press
edn: (edition)
yr: 2006
-pst: U.S.
+pl: U.S.
url: http://cyber.law.harvard.edu/wealth_of_networks/Main_Page
note:
sn: Benkler, /{Wealth of Networks}/ (2006)
@@ -2146,31 +2144,23 @@ 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)
+sn: Quixote & 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
+Note that the section name !biblio (or !bibliography) is required for the
+bibliography to be treated specially as such, 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:
+Using this method, work goes into preparing the bibliography, the tags author
+or editor, year and title are required and will be used to sort the
+bibliography that is placed under the Bibliography section
- 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 metadata tags may include shortname (sn:) and id, if provided, which are
+used for substitution within text. 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. }~
@@ -2179,6 +2169,30 @@ would be presented as:
Quixote and Panza, /Taming Windmills/ (1605), pp 1000 - 1001 also, Benkler,
/Wealth of Networks/, (2006) p 1 or rather[^11]
+au: author Surname, FirstNames (if multiple semi-colon separator)
+ (required unless editor to be used instead)
+ti: title (required)
+st: subtitle
+jo: journal
+vo: volume
+ed: editor (required if author not provided)
+tr: translator
+src: source (generic field where others are not appropriate)
+in: in (like src)
+pl: place/location (state, country)
+pb: publisher
+edn: edition
+yr: year (yyyy or yyyy-mm or yyyy-mm-dd) (required)
+pg: pages
+url: http://url
+note: note
+id: create_short_identifier e.g. authorSurnameYear
+ (used in substitutions: when found within text will be
+ replaced by the short name provided)
+sn: short name e.g. Author, /{short title}/, Year
+ (used in substitutions: when an id is found within text
+ the short name will be used to replace it)
+
----------------------------------------
@@ -2200,6 +2214,25 @@ 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.
+GLOSSARY
+........
+
+Using the section name 1~!glossary results in the Glossary being treated
+specially as such, and placed after the auto-generated endnote section (before
+the bibliography/list of references if there is one).
+
+The Glossary is ordinary text marked up in a manner deemed suitable for that
+purpose. e.g. with the term in bold, possibly with a hanging indent.
+
+1~!glossary
+
+_0_1 *{GPL}* An abbreviation that stands for "General Purpose License." ...
+
+_0_1 [provide your list of terms and definitions]
+
+In the given example the first line is not indented subsequent lines are by one
+level, and the term to be defined is in bold text.
+
BOOK INDEX
..........