diff options
Diffstat (limited to 'doc')
35 files changed, 5435 insertions, 0 deletions
diff --git a/doc/context/documents/general/manuals/mkiv-publications.pdf b/doc/context/documents/general/manuals/mkiv-publications.pdf Binary files differnew file mode 100644 index 000000000..a123306b2 --- /dev/null +++ b/doc/context/documents/general/manuals/mkiv-publications.pdf diff --git a/doc/context/documents/general/qrcs/setup-cs.pdf b/doc/context/documents/general/qrcs/setup-cs.pdf Binary files differindex 690eb03c6..dbd912c54 100644 --- a/doc/context/documents/general/qrcs/setup-cs.pdf +++ b/doc/context/documents/general/qrcs/setup-cs.pdf diff --git a/doc/context/documents/general/qrcs/setup-de.pdf b/doc/context/documents/general/qrcs/setup-de.pdf Binary files differindex d9ecba5bf..451f735b9 100644 --- a/doc/context/documents/general/qrcs/setup-de.pdf +++ b/doc/context/documents/general/qrcs/setup-de.pdf diff --git a/doc/context/documents/general/qrcs/setup-en.pdf b/doc/context/documents/general/qrcs/setup-en.pdf Binary files differindex d79bbd007..65537fd65 100644 --- a/doc/context/documents/general/qrcs/setup-en.pdf +++ b/doc/context/documents/general/qrcs/setup-en.pdf diff --git a/doc/context/documents/general/qrcs/setup-fr.pdf b/doc/context/documents/general/qrcs/setup-fr.pdf Binary files differindex 8ae79f67f..db6b246b3 100644 --- a/doc/context/documents/general/qrcs/setup-fr.pdf +++ b/doc/context/documents/general/qrcs/setup-fr.pdf diff --git a/doc/context/documents/general/qrcs/setup-it.pdf b/doc/context/documents/general/qrcs/setup-it.pdf Binary files differindex 4938a0db7..5db100c45 100644 --- a/doc/context/documents/general/qrcs/setup-it.pdf +++ b/doc/context/documents/general/qrcs/setup-it.pdf diff --git a/doc/context/documents/general/qrcs/setup-nl.pdf b/doc/context/documents/general/qrcs/setup-nl.pdf Binary files differindex 9ae7912eb..e24127ed2 100644 --- a/doc/context/documents/general/qrcs/setup-nl.pdf +++ b/doc/context/documents/general/qrcs/setup-nl.pdf diff --git a/doc/context/documents/general/qrcs/setup-ro.pdf b/doc/context/documents/general/qrcs/setup-ro.pdf Binary files differindex eda23ab37..3679fd3ad 100644 --- a/doc/context/documents/general/qrcs/setup-ro.pdf +++ b/doc/context/documents/general/qrcs/setup-ro.pdf diff --git a/doc/context/sources/general/manuals/publications/boekplan.bib b/doc/context/sources/general/manuals/publications/boekplan.bib new file mode 100644 index 000000000..5089388ed --- /dev/null +++ b/doc/context/sources/general/manuals/publications/boekplan.bib @@ -0,0 +1,93 @@ +@Book{Hagen2010metafun, + Title = {MetaFun}, + + Address = {Hassalt, NL}, + Author = {Hans Hagen}, + Edition = {2nd}, + Month = {October}, + Organization = {PRAGMA ADE}, + Year = {2010}, + + Abstract = {If you like graphics, you may like MetaFun, a collection of MetaPost macros. The manual covers most of MetaPost, as well as the interface between this graphical environment and ConTeXt. There are numerous examples, that give you an impression about the power of this graphical system as well as the strength of the combination with TeX. + +This is the second version of the MetaFun book. This version is adapted to ConTeXt MkIV that uses LuaTeX with MPlib. Although the book targets at ConTeXt users, much of the content concerns general usage of MetaPost, a small and fast system for making graphics.}, + Day = {8}, + File = {metafun-p.pdf}, + ISBN = {978-94-90688-02-8}, + Keywords = {MetaPost; ConTeXt; MkIV. LuaTeX}, + Language = {english}, + TotalPages = {375}, + Publisher = {Boekplan}, + Url = {http://www.h2o-books.com/catalog/context/metafun} +} + +@Book{Hagen2010mkii-mkiv, + Title = {MKII - MKIV, the history of LuaTeX}, + Author = {Hans Hagen}, + Publisher = {Boekplan}, + Year = {2010}, + + Address = {Hassalt, NL}, + Month = {October}, + + Abstract = {The objective of the LuaTeX project by Taco Hoekwater, Hartmut Henkel and Hans Hagen is to provide a versatile successor to TeX. During the development the team keeps track of ideas and experiments. In parallel ConTeXt MkIV is developed. This book describes the development of both systems and shows what impact the project has. The book start at version zero and ends with version 0.50, the first formal release.}, + Day = {30}, + Keywords = {ConTeXt; MkII; MkIV; LuaTeX}, + Language = {english}, + TotalPages = {328}, + Url = {http://www.h2o-books.com/catalog/context/mkii-mkiv} +} + +@Manual{Hagen2014bibliographies, + Title = {Bibliographies}, + + Address = {Hassalt, NL}, + Author = {Hans Hagen and Alan Braslau}, + Note = {still incomplete}, + Organization = {PRAGMA ADE \& \CONTEXT\ Development Team}, + Year = {2015}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + File = {mkiv-publications.pdf}, + Keywords = {manual}, + Language = {english}, + Review = {Review...}, + Subtitle = {The \CONTEXT\ way} +} + +@Book{Hoekwater2011fonts, + Title = {Fonts in ConTeXt}, + + Address = {Hassalt, NL}, + Author = {Taco Hoekwater and Hans Hagen}, + Month = {February}, + Year = {2011}, + + Abstract = {This booklet describes how to define and use fonts in ConTeXt. It demonstrates how to use individual fonts and provides examples of more complex setups for related font styles. Although ConTeXt comes with many fonts set up, this manual is a must-read for those who want to roll out their own setups.}, + Day = {18}, + ISBN = {978-94-90688-03-5}, + Keywords = {fonts; ConTeXt; MkIV; LuaTeX}, + Language = {english}, + TotalPages = {128}, + Publisher = {Boekplan}, + Url = {http://www.h2o-books.com/catalog/context/fonts} +} + +@Book{Hoekwater2011layouts, + Title = {Layouts in ConTeXt}, + + Address = {Hassalt, NL}, + Author = {Taco Hoekwater and Hans Hagen and Willi Egger}, + Month = {July}, + Year = {2011}, + + Abstract = {One of the principles behind ConTeXt is that you can create your own styles. Often defining a style starts with setting up the page layout. This booklet tells in detail how to do that. It also contains information on how to prepare your documents for professional printing, including page imposition.}, + Day = {11}, + ISBN = {978-94-90688-00-4}, + Keywords = {ConTeXt; MkIV; LuaTeX}, + Language = {english}, + TotalPages = {142}, + Publisher = {Boekplan}, + Url = {http://www.h2o-books.com/catalog/context/layouts} +} diff --git a/doc/context/sources/general/manuals/publications/duane.bib b/doc/context/sources/general/manuals/publications/duane.bib new file mode 100644 index 000000000..bc31a26e1 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/duane.bib @@ -0,0 +1,116 @@ +@IMAGE {tug2014, + title = "TUG 2014", + url = "http://tug.org/tug2014/", + url_image = "http://tug.org/art/tug2014-color.jpg", + url_thumb = "http://tug.org/tug2014/t2014-thumb.jpg", + description = "Official drawing of the TUG 2014 conference", + author = "Duane Bibby", + year = 2014, +} + +@IMAGE {tug2013, + title = "TUG 2013", + url = "http://tug.org/tug2013/", + url_image = "http://tug.org/tug2013/tug2013-color-300.jpg", + url_thumb = "http://tug.org/tug2013/t2013-thumb.jpg", + description = "Official drawing of the TUG 2013 conference", + author = "Duane Bibby", + year = 2013, +} + +@IMAGE {tug2012, + title = "TUG 2012", + url = "http://tug.org/tug2012/", + url_image = "http://www.tug.org/art/tug2012-color.jpg", + url_thumb = "http://www.tug.org/tug2012/t2012-thumb.jpg", + description = "Official drawing of the TUG 2012 conference", + author = "Duane Bibby", + year = 2012, +} + +@IMAGE {tug2011, + title = "TUG 2011: TeX in the eBook era", + url = "http://tug.org/tug2011/", + url_image = "http://www.tug.org/art/tug2011-boatrace.jpg", + url_thumb = "http://www.tug.org/tug2011/art/t2011-thumb.jpg", + description = "Official drawing of the TUG 2011 conference", + author = "Duane Bibby", + year = 2011, +} + +@IMAGE {tug2010, + title = "TUG 2010: TeX's $2^5$ anniversary", + url = "http://tug.org/tug2010/", + url_image = "http://www.tug.org/art/tug2010-color.jpg", + url_thumb = "http://www.tug.org/tug2010/t2010-thumb.jpg", + description = "Official drawing of the TUG 2010 conference", + author = "Duane Bibby", + year = 2010, +} + +@IMAGE {tug2009, + title = "TUG 2009", + url = "http://tug.org/tug2009/", + url_image = "http://www.tug.org/art/tug2009.jpg", + url_thumb = "http://www.tug.org/tug2009/t2009-thumb.jpg", + description = "Official drawing of the TUG 2009 conference", + author = "Duane Bibby", + year = 2009, +} + +@IMAGE {tug2008, + title = "TUG 2008", + url = "http://www.ucc.ie/archive/tug2008/", + url_image = "http://www.tug.org/art/tug2008.jpg", + url_thumb = "", + description = "Official drawing of the TUG 2008 conference", + author = "Duane Bibby", + year = 2008, +} + +@IMAGE {tug2007, + title = "TUG 2007", + url = "http://tug.org/tug2007/", + url_image = "http://www.tug.org/tug2007/t2007.jpg", + url_thumb = "http://www.tug.org/tug2007/t2007-thumb.jpg", + description = "Official drawing of the TUG 2007 conference", + author = "Duane Bibby", + year = 2007, +} + +% URL not working +@IMAGE {tug2006, + title = "TUG 2006", + url = "http://tug.org/tug2006/", + url_image = "http://www.tug.org/art/tug2006-color.jpg", + url_thumb = "", + description = "Official drawing of the TUG 2006 conference", + author = "Duane Bibby", + year = 2006, +} + +@IMAGE {tug2006bw, + title = "TUG 2006 b&w", + url = "http://tug.org/tug2006/", + url_image = "http://www.tug.org/art/tug2006-bw.jpg", + url_thumb = "", + colorspace = "gray", + description = "Official drawing of the TUG 2006 conference (black and white version)", + author = "Duane Bibby", + year = 2006, +} + + +@IMAGE {tug2005, + title = "TUG 2005", + url = "http://tug.org/tug2005/", + url_image = "http://www.tug.org/art/tug2005.jpg", + url_thumb = "", + description = "Official drawing of the TUG 200 conference", + author = "Duane Bibby", + year = 2005, +} + +% http://www.tug.org/art/ +% https://tug.org/meetings.html +% http://www.tug.org/tug2001/bulletin/bulletin.jpg diff --git a/doc/context/sources/general/manuals/publications/manuals.bib b/doc/context/sources/general/manuals/publications/manuals.bib new file mode 100644 index 000000000..00f5d9136 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/manuals.bib @@ -0,0 +1,47 @@ +@BOOK {h2o:layouts-in-context, + title = "Layouts in ConTeXt", + author = "Taco Hoekwater and Hans Hagen and Willi Egger", + year = 2011, + month = 07, + day = 11, + url = "http://www.h2o-books.com/node/12", + url_image = "http://www.h2o-books.com/sites/default/files/imagecache/product_full/layout-cover.png", + url_thumb = "http://www.h2o-books.com/sites/default/files/imagecache/product/layout-cover.png", + price = 24, +} + +@BOOK {h2o:fonts-in-context, + title = "Fonts in ConTeXt", + author = "Taco Hoekwater and Hans Hagen", + year = 2011, + month = 02, + day = 18, + url = "http://www.h2o-books.com/node/11", + url_image = "http://www.h2o-books.com/sites/default/files/imagecache/product_full/fonts-cover.png", + url_thumb = "http://www.h2o-books.com/sites/default/files/imagecache/product/fonts-cover.png", + price = 19, +} + +@BOOK {h2o:mkii-mkiv, + title = "MKII - MKIV, the history of LuaTeX", + author = "Hans Hagen", + year = 2010, + month = 10, + day = 30, + url = "http://www.h2o-books.com/node/10", + url_image = "http://www.h2o-books.com/sites/default/files/imagecache/product_full/mk-thumb.png", + url_thumb = "http://www.h2o-books.com/sites/default/files/imagecache/product/mk-thumb.png", + price = 49, +} + +@BOOK {h2o:metafun-manual, + title = "MetaFun manual", + author = "Hans Hagen", + year = 2010, + month = 10, + day = 10, + url = "http://www.h2o-books.com/node/9", + url_image = "http://www.h2o-books.com/sites/default/files/imagecache/product_full/metafun-thumb_0.png", + url_thumb = "http://www.h2o-books.com/sites/default/files/imagecache/product/metafun-thumb_0.png", + price = 49, +} diff --git a/doc/context/sources/general/manuals/publications/mkiv-publications.bib b/doc/context/sources/general/manuals/publications/mkiv-publications.bib new file mode 100644 index 000000000..15086e5b0 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/mkiv-publications.bib @@ -0,0 +1,680 @@ +@Comment{Start example} +@Article{article, + Title = {Article title}, + Title:fr = {Titre de l'article}, + Author = {First Last} + # { and First Middle Last} + # { and Last, First-Combined} + # { and First van Last} + # { and van Last, First Middle} + # { and Last, Junior, First Middle} + # { and van Last, Junior III, First Middle} + # { and De La, Last, Junior III, First Middle}, + Journal = {Journal name}, + Year = {YYYY}, + + Note = {note...}, + Number = {number}, + Pages = {ff--tt}, + Subtitle = {Subtitle}, + Type = {Special Issue}, + Volume = {volume}, + + Month = {MM-ignored!}, + Day = {DD-ignored!}, + Abstract = {Abstract...}, + Warning = {Notice that Comment= also exists}, + Comment = {Comment...}, + XCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {keyword1; keyword2; keyword3}, + Language = {english}, + Review = {Review...}, + Url = {url} +} +@Comment{Stop example} +@Article{article, + Title = {Article title}, + Title:fr = {Titre de l'article}, + Author = {First Last} + # { and First Middle Last} + # { and Last, First-Combined} + # { and First van Last} + # { and van Last, First Middle} + # { and Last, Junior, First Middle} + # { and van Last, Junior III, First Middle} + # { and De La, Last, Junior III, First Middle}, + Journal = {Journal name}, + Year = {YYYY}, + + Note = {note...}, + Number = {number}, + Pages = {ff--tt}, + Subtitle = {Subtitle}, + Type = {Special Issue}, + Volume = {volume}, + + Month = {MM-ignored!}, + Day = {DD-ignored!}, + Abstract = {Abstract...}, + Warning = {Notice that Comment= also exists}, + Comment = {Comment...}, + XCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {keyword1; keyword2; keyword3}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Comment{We define a few other instances of Article to test some realistic contingencies.} + +@Article{advancedonline, + Message = {This is an example of an advanced online publication.}, + Title = {Advanced article title}, + Author = {LastnameA, FirstnameA + and LastnameB, FirstnameB + and LastnameC, FirstnameC + and LastnameD, FirstnameD + and LastnameE, FirstnameE + and LastnameF, FirstnameF + and LastnameG, FirstnameG}, + Journal = {Journal name}, + + Language = {english}, + Url = {url}, +} + +@Magazine{magazine, + Message = {This is a magazine article.}, + Title = {Magazine article title}, + Author = {MagazineLastname, Firstname}, + Journal = {Magazine name}, + Year = {YYYY}, + + Month = {Month}, + Day = {DD}, + Note = {note...}, + Number = {number}, + Pages = {ff--tt}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Keywords = {magazine}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Newspaper{newspaper, + Message = {This is a newspaper article.}, + Title = {Article title}, + Author = {NewspaperLastname, Firstname}, + Journal = {Newspaper name}, + Year = {YYYY}, + + Month = {Month}, + Day = {DD}, + Note = {note...}, + Number = {number}, + Pages = {ff--tt}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Keywords = {newspaper}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Newspaper{editorial, + Message = {This is a newspaper editorial.}, + Editor = {EditorLastname, Firstname}, + Title = {Editorial title}, + Journal = {Newspaper name}, + Year = {YYYY}, + + Month = {Month}, + Day = {DD}, + Note = {note...}, + Number = {number}, + Pages = {ff--tt}, + Type = {Editorial}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Keywords = {editorial}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Book{book, + Title = {Book title}, + Title = {Title2}, + Author = {BookAuthorLastnameA, Firstname + and BookAuthorLastnameB, Firstname Middle + and BookAuthorLastnameC, Firstname-Combined}, + Editor = {EditorLastname, Firstname}, + Editor = {EditorLastname2, Firstname}, + Publisher = {Publisher}, + Year = {YYYY}, + + Address = {Address}, + Edition = {edition}, + Month = {Month}, + Note = {note...}, + Number = {number}, + Series = {series}, + Type = {Translated title, for example}, + Volume = {volume}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {book}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Book{selfpublished, + Title = {Book title}, + Author = {BookAuthorLastname, Firstname}, + Author = {BookAuthorLastname2, Firstname}, + Year = {YYYY}, + + Address = {Address}, + + Comment = {A self-published book}, + Language = {english}, +} + +@Book{editedbook, + Editor = {EditorLastnameA, Firstname + and EditorLastnameB, Firstname}, + Publisher = {Publisher}, + Title = {Book title}, + Year = {YYYY}, + + Address = {Address}, + + Comment = {Editors as authors}, + Language = {english}, +} + +@Book{noauthor, + Title = {Book title}, + Publisher = {Publisher}, + Year = {YYYY}, + + Address = {Address}, + + Comment = {Publisher as author}, + Language = {english}, +} + +@Booklet{booklet, + Title = {Booklet title}, + + Address = {Address}, + Author = {BookletAuthorLastname, Firstname}, + HowPublished = {howpublished}, + Month = {Month}, + Note = {note...}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {booklet}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Conference{conference, + Title = {Conference title}, + Author = {ConferenceAuthorLastname, Firstname}, + Booktitle = {Booktitle}, + Year = {YYYY}, + + Address = {Address}, + Editor = {EditorLastname, Firstname}, + Month = {Month}, + Note = {note...}, + Number = {number}, + Organization = {<Symposium conducted at the meeting of> Organization}, + Pages = {ff--tt}, + Publisher = {publisher}, + Series = {series}, + Volume = {volume}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {conference}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Electronic{electronic, + Title = {Electronic title}, + + Address = {Address}, + Author = {ElectronicAuthorLastname, Firstname}, + HowPublished = {howpublished}, + Language = {english}, + Month = {Month}, + Note = {note...}, + Organization = {Organization}, + Url = {url}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {electronic}, + Review = {Review...}, +} + +@Film{film, + Title = {Film title}, + + Director = {DirectorLastname, Firstname}, + Producer = {ProducerLastName, Firstname}, + Publisher = {studio}, + Address = {address}, + Note = {note...}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Keywords = {misc}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@InBook{inbook, + Title = {InBook title}, + Author = {InBookAuthorLastname, Firstname}, + Chapter = {Chapter title}, + Editor = {EditorLastname, Firstname}, + Pages = {ff--tt}, + Publisher = {publisher}, + Year = {YYYY}, + + Address = {Address}, + Edition = {edition}, + Month = {Month}, + Note = {note...}, + Number = {number}, + Series = {series}, + Type = {type}, + Volume = {volume}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {inbook}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@InCollection{incollection, + Title = {InCollection title}, + Author = {InCollectionAuthorLastname, Firstname}, + Booktitle = {Booktitle}, + Publisher = {publisher}, + Year = {YYYY}, + + Address = {Address}, + Chapter = {Chaptertitle}, + Edition = {edition}, + Editor = {EditorLastname, Firstname}, + Month = {Month}, + Note = {note...}, + Number = {number}, + Pages = {ff--tt}, + Series = {series}, + Type = {type}, + Volume = {volume}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {incollection}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@InProceedings{inproceedings, + Title = {InProceedings title}, + Author = {InProceedingsAuthorLastname, Firstname}, + Booktitle = {Booktitle}, + Year = {YYYY}, + + Address = {Address}, + Editor = {EditorLastname, Firstname}, + Month = {Month}, + Note = {note...}, + Number = {number}, + Organization = {<Symposium conducted at the meeting of> Organization}, + Pages = {ff--tt}, + Publisher = {publisher}, + Series = {series}, + Volume = {volume}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {inproceedings}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Manual{manual, + Title = {Manual title}, + + Address = {Address}, + Author = {ManualLastname, Firstname}, + Edition = {Edition}, + Month = {Month}, + Note = {note...}, + Organization = {Organization}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + Doi = {doi-specification}, + Keywords = {manual}, + Review = {Review...}, + Url = {url} +} + +@MastersThesis{mastersthesis, + Title = {MastersThesis title}, + Author = {MastersThesisAuthorLastname, Firstname}, + School = {school}, + Year = {YYYY}, + + Address = {Address}, + Month = {Month}, + Note = {note...}, + Type = {type}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {mastersthesis}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Thesis{thesis, + Title = {Thesis title}, + Author = {ThesisAuthorLastname, Firstname}, + School = {school}, + Year = {YYYY}, + + Address = {Address}, + Month = {Month}, + Note = {note...}, + Type = {type of thesis}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {mastersthesis}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Misc{misc, + Title = {Misc title}, + + Author = {MiscAuthorLastname, Firstname}, + HowPublished = {howpublished}, + Month = {Month}, + Note = {note...}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {misc}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Music{music, + Title = {Music title}, + Album = {Album title}, + + Artist = {ArtistLastname, Firstname}, + Composer = {ComposerLastName, Firstname}, + Publisher = {label}, + Address = {address}, + Note = {note...}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Keywords = {misc}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Other{other, + Title = {Other title}, + Abstract = {Abstract...}, + Author = {OtherAuthorLastname, Firstname}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {other}, + Language = {english}, + Note = {note...}, + Review = {Review...}, + Url = {url}, + Year = {YYYY} +} + +@Patent{patent, + Title = {Patent title}, + Nationality = {nationality}, + Number = {number}, + Year = {YYYY}, + Yearfiled = {YYYYfiled}, + Author = {PatentAuthorLastname, Firstname}, + Language = {english}, + Note = {note...}, + Url = {url}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {patent}, + Review = {Review...}, +} + +@Periodical{periodical, + Title = {Periodical title}, + + Editor = {EditorLastname, Firstname}, + Language = {english}, + Month = {Month}, + Note = {note...}, + Number = {number}, + Organization = {Organization}, + Series = {series}, + Url = {url}, + Volume = {volume}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Author = {PeriodicalAuthorLastname, Firstname}, + Journal = {Periodical Journal}, + Comment = {Complete issue of a periodical, such as + a special issue of a journal}, + PercentCrossref = {crossref}, + Day = {DD}, + Keywords = {periodical}, + Review = {Review...}, +} + +@PhdThesis{phdthesis, + Title = {PhDThesis title}, + Author = {PhDThesisAuthorLastname, Firstname}, + School = {school}, + Year = {YYYY}, + Note = {note...}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {phdthesis}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Proceedings{proceedings, + Title = {Proceedings title}, + Year = {YYYY}, + + Address = {Address}, + Editor = {EditorLastname, Firstname}, + Month = {Month}, + Note = {note...}, + Number = {number}, + Organization = {<Symposium conducted at the meeting of> Organization}, + Publisher = {Publisher}, + Series = {series}, + Volume = {volume}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {proceedings}, + Review = {Review...}, + Url = {url} +} + +@Proceedings{proceedings-organization, + Title = {Proceedings title}, + Year = {YYYY}, + + Address = {Address}, + Month = {Month}, + Day = {DD}, + Note = {note...}, + Number = {number}, + Organization = {Organization}, + Publisher = {Publisher}, + Series = {series}, + Volume = {volume}, + + Abstract = {Abstract...}, + Comment = {Conference preceedings with no identified editor(s)}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {proceedings}, + Review = {Review...}, + Url = {url} +} + +@Standard{standard, + Title = {Standard title}, + Institution = {institution}, + Organization = {Organization}, + Author = {StandardAuthorLastname, Firstname}, + Language = {english}, + Note = {note...}, + Url = {url}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {standard}, + Review = {Review...}, +} + +@TechReport{techreport, + Title = {TechReport title}, + Author = {TechReportAuthorLastname, Firstname}, + Institution = {institution}, + Year = {YYYY}, + + Address = {Address}, + Month = {Month}, + Note = {note...}, + Number = {number}, + Type = {type}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {techreport}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Unpublished{unpublished, + Title = {Unpublished title}, + Author = {UnpublishedAuthorLastname, Firstname}, + Note = {note...}, + + Month = {Month}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {unpublished}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Literal{literal, + Key = {ZZZZ-end}, + Text = {Copied literally to the bibliography}, +} + +@Book{selfpublished2, + Crossref = selfpublished, + Author = {BookAuthorLastname2, Firstname}, +} diff --git a/doc/context/sources/general/manuals/publications/mkiv-publications.lua b/doc/context/sources/general/manuals/publications/mkiv-publications.lua new file mode 100644 index 000000000..f6a980f3e --- /dev/null +++ b/doc/context/sources/general/manuals/publications/mkiv-publications.lua @@ -0,0 +1,30 @@ +return { + ["GH0001"] = { + category = "book", + title = "Rhythmic Illusions", + subtitle = "for drums", + author = "Gavin Harrison", + publisher = "Warner", + isbn = "1576236870", + year = "1996", + comment = "plus cd", + }, + ["GH0002"] = { -- no reference in brittisch library + category = "book", + title = "Rhythmic Perspectives", + subtitle = "a multidimensional study of rhythmic composition", + author = "Gavin Harrison", + publisher = "Alfred Publishing Co., Inc", + year = "1999", + comment = "plus cd", + }, + ["GH0003"] = { + category = "book", + title = "Rhythmic Designs", + subtitle = "a study of practical creativity", + author = "Gavin Harrison and Terry Branham", + publisher = "Hudson", + year = "2010", + comment = "plus dvd", + }, +} diff --git a/doc/context/sources/general/manuals/publications/mkiv-publications.tex b/doc/context/sources/general/manuals/publications/mkiv-publications.tex new file mode 100644 index 000000000..e5d41fe2f --- /dev/null +++ b/doc/context/sources/general/manuals/publications/mkiv-publications.tex @@ -0,0 +1,63 @@ +% language=en % uk - Is behaviour really better than behavior, defence than defense? + +% todo : index key in chapters + +% \enabletrackers[publications*] +% \enabletrackers[publications.cite.match] +% \enabletrackers[publications.setups] +% \enabletrackers[publications.authorhash] + +% We use the following bib files: +% +% tugboat.bib +% template2.bib +% +% boekplan.bib +% duane.bib +% manuals.bib +% +% mkiv-publications.bib +% mkiv-publications.lua + +\environment publications-style + +\startdocument + [title={Bibliographies}, + subtitle={The \CONTEXT\ way}, + author={Hans Hagen and Alan Braslau}] + +\component publications-titlepage + +\startfrontmatter + \component publications-contents + \component publications-introduction +\stopfrontmatter + +\startbodymatter + \component publications-quick + \component publications-database + \component publications-datasets + \component publications-rendering + \component publications-citations + \component publications-customize + \component publications-exporting + \component publications-lua + \component publications-xml + \component publications-extensions + % \component publications-journals + \component publications-otheruse + \component publications-tracing +\stopbodymatter + +\startappendices + \component publications-fields + \component publications-completeness + \component publications-transition + \component publications-performance +\stopappendices + +\startbackmatter + \component publications-overviews +\stopbackmatter + +\stopdocument diff --git a/doc/context/sources/general/manuals/publications/publications-citations.tex b/doc/context/sources/general/manuals/publications/publications-citations.tex new file mode 100644 index 000000000..fca48b313 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-citations.tex @@ -0,0 +1,870 @@ +\environment publications-style + +\startcomponent publications-citations + +\startchapter + [title=Citations, + reference=ch:cite] + +The \index {style+APA}APA Style Guide as well as good practice demand that +\emphasis {all} references appearing in the bibliography be cited at least once +in the text (and, of course, all citations must have a corresponding +bibliographical reference). Other publishing styles, textbooks in particular, +might additionally include lists of general references for \quote {further +reading} (and these lists might sometimes be split into sections according to +subject). An author may, in contrast, choose not to interrupt a text with many +citations, nevertheless, including a list of references. Furthermore, one might +refer in the text to certain works that need not necessarily be accompanied by a +full bibliography listing (for example, \Name {Darwin} {C.}'s \emph {Origin}). +\startfootnote \textcite[entry] [default::Darwin1859] \stopfootnote Thus, a +system providing tools to handle bibliographies needs to be flexible. + +A good, general reference on bibliography practice (in the English language), +independent of any particular specification, can be found in \cite [title] +[default::vanLeunen1992] \cite [default::vanLeunen1992]. Note that rules and +traditions may differ slightly in other languages and cultures. + +The examples of bibliography listings of the previous chapter were simplified by +the fact that the entire bibliographical dataset was rendered. In practice, the +same dataset source(s) could be used over many documents, and the dataset might +contain many more references than are used in any one document. That is, the data +source might be more complete than the final rendered bibliography list or lists. +The mechanism of citation allows you to select references from the dataset(s) to +build the list rendering as well as to place a indicator of the reference (or +not) in the text of the document corresponding to a list entry (a publication). +These citation renderings can be of many forms. + +A citation is normally pretty short as its main purpose is to refer uniquely to a +more detailed description. But, there are several ways to refer, which is why the +citation subsystem is configurable and extensible. Just look at the following +commands: + +\cindex{cite} +\tindex{::} + +\starttabulate +\NC \TEXcode{\cite[num][article]} \NC \cite[num] [article] \NC \NR +\NC \TEXcode{\cite[textnum][article]} \NC \cite[textnum] [article] \NC \NR +\NC \TEXcode{\cite[authornum][article]} \NC \cite[authornum] [article] \NC \NR +\NC \TEXcode{\cite[authoryear][article]} \NC \cite[authoryear] [article] \NC \NR +\NC \TEXcode{\cite[authoryears][article]} \NC \cite[authoryears][article] \NC \NR +\NC \TEXcode{\cite[short][article]} \NC \cite[short] [article] \NC \NR +\NC \TEXcode{\cite[tag][article]} \NC \cite[tag] [article] \NC \NR +\NC \TEXcode{\cite[index][article]} \NC \cite[index] [article] \NC \NR +\NC \TEXcode{\cite[category][article]} \NC \cite[category] [article] \NC \NR +\NC \TEXcode{\cite[author][article]} \NC \cite[author] [article] \NC \NR +\NC \TEXcode{\cite[year][article]} \NC \cite[year] [article] \NC \NR +\NC \TEXcode{\cite[title][article]} \NC \cite[title] [article] \NC \NR +\NC \TEXcode{\cite[keywords][article]} \NC \cite[keywords] [article] \NC \NR +\NC \TEXcode{\cite[none][article]} \NC \cite[none] [article] \NC \NR +\NC \TEXcode{\cite[X]} \NC \cite[X] \NC \NR +\NC \TEXcode{\cite[]} \NC \cite[] \NC \NR +\NC \TEXcode{\cite[template::Chen:1988:IPP]} \NC \cite[template::Chen:1988:IPP] \NC \NR +\NC \TEXcode{\cite[entry][article]} \NC \cite[entry] [article] \NC \NR +\stoptabulate + +The first argument is optional and if omitted, the default citation rendering +(for example, \TEXcode {num} or \TEXcode {authoryear}, depending on the +specification) will be selected. + +\startbuffer +\cite[article] +\stopbuffer +\cindex{cite} + +\typeTEXbuffer \getbuffer + +\startaside +The default citation alternative is defined via \cindex {setupbtx} + +\startTEX +\setupbtx[alternative=num] +\stopTEX + +However, this is not used as it is overridden by the specification, even the +\TEXcode {default} specification: + +\startTEX +\setupbtx[default:cite][alternative=num] +\setupbtx [apa:cite][alternative=authoryear] +\stopTEX + +These examples introduce the concept of \Index {namespace}s that is extensively +used in the bibliography subsystem. The \TEXcode {cite} namespace will inherit +from the root namespace; similarly, the \TEXcode {default} specification will +inherit elements from the \TEXcode {cite} namespace, but will be distinct from +the \TEXcode {apa} specification's \TEXcode {cite} namespace, and so forth. +Normally, we need not to worry about this as it is handled through the loading of +the specification. +\stopaside + +\cindex {cite} +\showsetup[cite] + +The \Cindex{citation} command is synonymous to \Cindex{cite}. + +\cindex {citation} +\showsetup[citation] +%\showsetup[citation:userdata] +\showsetup[citation:alternative] +\showsetup[citation:direct] + +\startaside +Note that the \MKII\ module based on \Tindex {bibtex} allowed the use of curly +brackets enclosing the \Index {tag} (for reasons of backward compatibility with +traditional \LATEX\ practice). A side|-|effect made this a bit picky about spaces +between its arguments, the first of which is optional. We have chosen to remove +this restriction through the use of standard \CONTEXT\ syntax using square +brackets (reserving curly brackets to usually be used to enclose text that is to +be typeset). + +The system will tolerate the \Index {depreciated} syntax \cindex {cite}\TEXcode +{\cite{tag}}, but this practice is to be strongly discouraged and cannot be mixed +with any other options. +\stopaside + +The most commonly used citation variants (or alternatives) are \TEXcode {num} and +\TEXcode {authoryear} introduced above. The first is typically employed in +conjunction with a numbered bibliography list, usually sorted in the citation +order in the text; the second is typically used in conjunction with a +bibliography list sorted by author and year of publication. + +Other citation variants may be quite useful, even when used in the context of the +above standard schemes. One such example would be \Cindex {cite}\TEXcode +{[title][tag]} that can be used to include the title of the work in the running +text (as can be seen earlier in \in {section} [sec:styles]; another one is +\cindex {cite}\TEXcode {\cite[year][tag]} that can be used to include the +publication date and \cindex {cite}\TEXcode {\cite[author][tag]} can be used to +extract the authors' names. These are examples of a general rule where \cindex +{cite}\TEXcode {\cite[field][tag]} will return the contents of the given field +for an entry, if the entry contains such a field. + +The variants \TEXcode {textnum} and \TEXcode {authoryears} are intended to be +used in the running text when the reference becomes part of the syntax of the +sentence: typically, they will not be set|-|off by parenthesis, for example. + +\startaside +The name \TEXcode {authoryears} (with an \quote{s}) is a shorthand that was used +in \MKII. Whereas its name is not immediately obvious at first view, in practice +it is a quite convenient variant of \TEXcode {authoryear} that differs only in +the style of punctuation, thus its place in a sentence structure. +\stopaside + +Notice that in the example \TEXcode{\cite[template::Chen:1988:IPP]} shown above, +the \TEXcode {tag} was prefixed with an alternate dataset name (\tindex +{::}\TEXcode {template::}) rather than to the default \TEXcode {dataset=example} +that was specified in the \Cindex {setupbtx} command earlier. The reason behind +the double|-|colon syntax should be made obvious here (where the \Index {tag} +itself uses single colons). + +In the last of the examples shown above, \TEXcode{\cite[entry][article]}, the +full rendered bibliographic entry gets placed. + +Unless the placed rendering uses \TEXcode {method=dataset}, only publications +that are explicitly cited will end up in the lists. You can force a citation into +a list using \Cindex {usecitation}, for example: + +\cindex{usecitation} + +\startTEX +\usecitation[patent] +\stopTEX + +This command has two synonyms: \Cindex {nocite} and \Cindex {nocitation} so you +can choose whatever fits you best. + +\cindex {nocite} +\showsetup[nocite] + +\cindex {nocitation} +\showsetup[nocitation] + +The purpose and utility of these commands (and their synonyms) is not only to +draw a citation from the dataset for inclusion in the bibliography, but also to +mark the place in the text where the citation is relevant. Normally, one might +claim that this should be done through one of the forms of the \Cindex {cite} (or +\Cindex {citation}) command, as all references appearing in the bibliography are +to be cited at least once in the text. However, even if one does not disagree +with this statement, one might still wish attach the citation to the reference in +the text of a \Index {floating object} such as a table or a figure, thus +establishing a proper order in the numbering since the explicit citation +rendering might occur within the table or the figure caption that might get +placed on a much later page. Consider the following schematic illustration: + +\cindex{nocite} +\cindex{cite} + +\startTEX +(see \nocite [MyReference]\in {table} [tab:mytable]). + +\startplacetable[reference=tab:mytable] + \unknown\ \cite[MyReference] +\stopplacetable +\stopTEX + +The citation rendering and the bibliographic list rendering are intimately +coupled reciprocally and cannot be dissociated. This coupling can be through the +reference number for example, but unnumbered reference lists also contain +interacting hyperlinks. A failure to take into account this interdependence can +lead to fundamental misunderstandings in use. + +\startaside +Both the citation and the list must be rendered. For example, a common error +would be to omit (or comment|-|out) the list rendering during the writing stage +of a document. Such an error will cause the citations to fail to render properly. + +Whereas this might seem to be an unnecessary limitation, it results from a +specific design choice and from the possibility of placing multiple renderings +freely, anywhere in a document. It is preferable not to render citations at all +than to render these citations possibly incorrectly. +\stopaside + +\startsection[title=Combining citations] + +\startbuffer +\cite[num][article,book,booklet] +\stopbuffer + +A single citation might refer to several sources, obtained through the use of a +comma separated list of \Index{tag}s, for example: \getbuffer + +\cindex{cite} + +\typeTEXbuffer + +A comma separated list of three (or more) consecutive numbers will get collapsed +or compressed into a range of numbers (if possible). + +\cindex {cite} The order in which the citation \Index {tag}s appear in the list +may or may not be important, depending upon the citation variant and on the style +specification. Consider the following examples: + +\startbuffer +\cite[num] [article,book] +\cite[textnum] [article,book] +\cite[authoryear] [article,book] +\cite[authoryears][article,book] +\cite[short] [article,book] +\cite[author] [article,book] +\cite[year] [article,book] +\cite[title] [article,book] +\stopbuffer + +\typeTEXbuffer + +This gives: + +\cindex{cite} +\startlines \getbuffer \stoplines + +Now we swap the order: + +\startbuffer +\cite[num] [book,article] +\cite[textnum] [book,article] +\cite[authoryear] [book,article] +\cite[authoryears][book,article] +\cite[short] [book,article] +\cite[author] [book,article] +\cite[year] [book,article] +\cite[title] [book,article] +\stopbuffer + +\typeTEXbuffer + +and get: + +\startlines \getbuffer \stoplines + +Note that the numbered citation reference is always rendered in numerical order, +where the numbers correspond to the order in which the entries appear in the +bibliography list. This order depends on the \Index {sorting} of the list +rendering (this sorting may be, in some styles, in the order in which the +references are cited) and is controlled by the \TEXcode {[list]} \TEXcode +{sorttype} parameter. In the \index {style+APA}APA style, presently active, the +citations are always sorted according to author and year. Thus, \quotation +{BookAuthorLastname} appears before \quotation {Last} in our example here, +regardless of the order in which the references appear in the \Cindex {cite} +command (i.e. either \TEXcode {\cite[article,book]} or \TEXcode +{\cite[book,article]}). + +The user can control the state of sorting of the \cindex{cite}\TEXcode {cite} +variants through the parameter \TEXcode {sorttype=normal}; other choices are +\TEXcode {reverse} and \TEXcode {none}: + +\startTEX +\setupbtx[aps:cite:num][sorttype=none] +\stopTEX + +\startsubsubject [title=Single list item containing multiple publication entries] + +Some bibliography styles admit the combination of several bibliographical sources +into a single list item having a unique reference number. The combination of +multiple bibliographic entries into as single bibliography list item is more +compact and this practice is often encountered in short \quote {letter}|-|type +journal articles. (Note, however, that entries combined as such do not make any +sense in an authoryear scheme such as \index {style+APA}APA.) + +One can combine \Index {tag}s using the addition operator symbol (\TEXcode {+}), +best illustrated though an example: + +\startbuffer +\METAFUN\ began as an expression of love and appreciation for \METAPOST. +\citation [num] [tugboat::Berdnikov:TB21-2-129+Hobby:TB21-2-131] + +\definebtxrendering[tugboat][aps][dataset=tugboat,group=examples] +\placebtxrendering [tugboat][criterium=section] +\stopbuffer + +\cindex{citation} +\cindex{definebtxrendering} +\cindex{placebtxrendering} +\tindex{::} + +\typeTEXbuffer + +\getbuffer + +% To Hans: We need to suppress the closing period before the combining semi-colon. +% To Alan: Can't we use \removepunctuation ? + +Combined entries are joined using a separator that can be specified, as in: + +\startbuffer +\setupbtxrendering[tugboat][separator={\break}] +\stopbuffer + +\cindex{setupbtxrendering} +\tindex{separator} + +\typeTEXbuffer + +or suppressed (using \tindex {separator}\TEXcode {separator=,}); By default, +\cindex {removepunctuation}\TEXcode {separator={\removepunctuation;\space}}. + +Dataset entries that are combined cannot also appear apart (nor does this really +make any logical sense). All of the following: + +\startbuffer +\cite[num][tugboat::Berdnikov:TB21-2-129] +\cite[num][tugboat::Berdnikov:TB21-2-129,Hobby:TB21-2-131] +\cite[num][tugboat::Hobby:TB21-2-131] +\stopbuffer +\cindex{cite} +\tindex{::} + +\typeTEXbuffer \getbuffer + +will point to the combined reference (as they should). However, beware that +attempting to include any of these references in a \emphasis {different} combined +list item is undefined, meaning unsupported. + +Combining list entries is another instance showing that citations and the +rendered bibliography list interact and cannot be separated. + +\stopsubsubject + +\stopsection + +\startsection[title=Additional text] + +\startsubsubject [title=Additional text in a citation reference] + +Sometimes one would like to include additional text in a citation, for example +a specific commentary or page number reference. + +\startbuffer +\cite[righttext={ p.\nbsp xx}][article] +\stopbuffer + +\cindex{cite} + +\typeTEXbuffer + +yielding: + +\getbuffer + +The additional text can be either before (\TEXcode {lefttext=}) or after +(\TEXcode {righttext=}) \startfootnote The \MKII\ bib module used the keyword +\TEXcode {extra=} in the place of \TEXcode {righttext=}. We chose not to support +this as a synonym as the name is ambiguous. Furthermore, we seek to limit the +number of keywords used in \CONTEXT. \stopfootnote each citation entry and are +not to be confused with the delimiters \TEXcode {left={(},} and \TEXcode +{right={)},} used to surround the entire citation. The difference becomes +important when referencing multiple citations. + +The following examples further illustrate the syntax: + +\startbuffer +\cite[lefttext={See },righttext={ p.\nbsp yy}][book] +\stopbuffer + +\typeTEXbuffer \getbuffer + +\startbuffer +\cite[alternative=num,righttext={{ p.\nbsp xx},{ p.\nbsp yy}}] + [article,book,booklet] +\stopbuffer + +\cindex{cite} + +\typeTEXbuffer \getbuffer + +\startbuffer +\cite[lefttext={In the article: },righttext={.}][article] +\stopbuffer + +\cindex{cite} + +\typeTEXbuffer \getbuffer + +\startbuffer +\cite[lefttext={{In the article: },{in the book: }},alternative=title] + [article,book] +\stopbuffer + +\cindex{cite} + +\typeTEXbuffer \getbuffer + +% To Hans: the text should probably NOT get the title's style (italics). +% To Alan: is this still an issue? I fixed the 'and'. + +Notice that the text is typeset using the \TEXcode {style} of the \TEXcode +{title}. + +\startbuffer +\cite[righttext={{ p.\nbsp xx},}][article,book] +\stopbuffer + +\cindex{cite} \typeTEXbuffer \getbuffer + +Because \CONTEXT\ does not allow mixing key|-|value pair lists with single value +keys, the keyword \TEXcode {alternative=} must be used, if needed, as shown in +the examples above. + +\stopsubsubject + +\startsubsubject [title=Additional text in a list entry] + +Additional text such as notes and page numbers can also get placed with the entry +in the bibliography list. Of course, the bibliography data entry can contain a +\TEXcode {note=} field that may or may not get rendered, but often is, according +to the style specification. + +It is also possible to specify notes or page references to be rendered \TEXcode +{before} or \TEXcode {after} a bibliography entry through the citation call. + +\startbuffer +\cite + [alternative=num, + before={{Introducing MetaPost: },}, + after={,{ See, also, the references therein, p.\nbsp 58.}}] + [tugboat::Hobby:TB10-4-505,Hobby:TB22-1-46] +\blank +\placebtxrendering [tugboat][criterium=section] +\stopbuffer + +\cindex{cite} +\cindex{placebtxrendering} +\tindex{::} + +\typeTEXbuffer \getbuffer + +Clearly, such additional text can be added to each entry only once, so the first +such \Cindex {cite} call wins. + +\stopsubsubject + +\stopsection + +\startsection[title=Placing a single citation] + +Sometimes, one would like to place a single citation somewhere in the text +without necessarily adding it to a bibliography list. Take, for example, + +\startbuffer +\placecitation[tugboat::Mahajan:TB31-1-88] +\stopbuffer + +\getbuffer + +obtained by using + +\cindex{placecitation} +\tindex{::} + +\typeTEXbuffer + +Note that \Cindex {placecitation}\TEXcode {[tag]} is a synonym for \Cindex +{citation}\TEXcode {[entry][tag]} (that was seen earlier). + +\showsetup[placecitation] + +As for other citation reference, this will fail if a bibliography list rendering +is not placed somewhere in the document so let's do that here: + +\startbuffer +\placebtxrendering[tugboat][criterium=section] +\stopbuffer + +\cindex{placebtxrendering} + +\typeTEXbuffer \getbuffer + +Whereas this might seem redundant above (placing the citation entry as well as +its list rendering), this will only exceptionally be the case (as in this highly +artificial example of this manual); Indeed, all cited work (such as \cite +[textnum] [tugboat::Mahajan:TB31-1-88], above) will logically always be placed in +a list of references. + +The placement of a single citation brings to light a subtle point: The \TEXcode +{specification} that is used by citations is that set in the root namespace +(through \Cindex {setupbtx}\TEXcode {[specification=apa]} or possibly through +\Cindex {usebtxdefinitions}\TEXcode {[apa]}. This is \emphasis {not} necessarily +the same as that of the rendering (if a different rendering specification is +declared). Note that the named rendering used above (\TEXcode {[tugboat]}) was +not declared a child of the rendering named \TEXcode {[aps]}, though the \TEXcode +{specification=apa} is active. Thus, the style of the citations can be made to +differ from the style of their bibliography list, as here, but this is not really +a very good practice. + +\stopsection + +\startsection[title=Placing citations as footnotes] + +A \Cindex {placecitation} command can occur inside a footnote or other \Index +{floating object} such as a figure or table caption. No specification or style +that places its bibliography list renderings as footnotes has been implemented +yet. + +% bibliographies as endnotes intercalated with footnotes... + +\stopsection + +\startsection[title=Searching] + +Finding the right \Index {tag} in a database can be a pain. In particular, +datasets having their origin in multiple source files may contain conflicting +\Index {tag}s, though duplicate \Index {tag}s get suffixed automatically so this +should not be a real problem. + +On the other hand, asking for a \Index {wildcard} also makes no sense. +\startfootnote Note that \cindex {nocite}\TEXcode {\nocite{*}} is a valid +\LATEX/\BIBTEX\ practice that is used to include all entries of a \Tindex {.bib} +file in the final bibliography. This result can be obtained in \CONTEXT\ through +the \TEXcode {method=dataset} list rendering parameter. Alternately, one can use +the syntax \cindex {cite}\TEXcode {\cite[match(*:*)]} which is a shorthand to +match all values of all fields. \stopfootnote Nevertheless, we provide a powerful +mechanism for matching a query. Keep in mind that a \Index {tag} is used as a +quick look|-|up in a hashed table whereas a search will look through the entire +dataset. If processing speed is critical, one should use the cite \Index {tag} +lookup; in practice, even on a big book project employing a very large dataset, +the search is not a penalty. + +Let's look in more detail at the \Cindex {cite} command. In order to distinguish +efficiently between a normal reference and a more clever one, we use the \TEXcode +{match()} function: + +\tindex{::} +\startTEX +match(query) +dataset::match(query) +dataset :: match ( query ) +\stopTEX + +The handler is rather tolerant for spaces (as well as capitalization) which is +handy if you have long queries that wrap around in the source code. Of course the +\tindex {::}\TEXcode {dataset::} prefix is optional in which case the current +dataset is taken. Such match queries can be mixed in a multiple reference +citation indifferently with hashed cite \Index {tag}s so the system is really +flexible. + +\blank + +To demonstrate the use a search query, we load a small bibliographic database: + +\startbuffer +\usebtxdataset[boekplan][boekplan.bib] +\stopbuffer + +\cindex{usebtxdataset} + +\typeTEXbuffer + +\getbuffer + +We could switch to this base using: + +\cindex{setupbtx} +\startTEX +\setupbtx[dataset=boekplan] +\stopTEX + +but instead we shall use a prefix as seen previously. Consider the following: + +\startbuffer +everything that you might want to know about layouts +\cite[boekplan::match(author:Egger)] +\stopbuffer + +\cindex{cite} +\tindex{::} + +\typeTEXbuffer + +We will get: \quotation {\inlinebuffer}. Of course this assumes that we also +typeset a list of references somewhere in our document, so let's do that here: + +\startbuffer +\definebtxrendering[boekplan][apa][dataset=boekplan,group=examples] +\placebtxrendering [boekplan][criterium=chapter] +\stopbuffer + +\cindex{definebtxrendering} +\cindex{placebtxrendering} + +\typeTEXbuffer \getbuffer + +\startbuffer +\cite[authoryears][ match(title:Lua)]\\ +\cite[authoryears][default:: match(title:Lua)]\\ +\cite[authoryears][boekplan::match(title:Lua)] +\stopbuffer + +\cindex{cite} +\tindex{::} + +\typeTEXbuffer \getbuffer + +Notice that no match is found in the \quote {current} dataset (\TEXcode {example}). + +A query eventually becomes a \LUA\ expression so you can use helpers to achieve +your goal. As a convenience there are some shortcuts to access fields. The +following examples demonstrate this: + +\startbuffer +\cite + [authoryears] + [boekplan::match(author:hagen and year:2010-2011)]\\ +\cite + [authoryears] + [boekplan::match(author:{Willi Egger})]\\ +\cite + [authoryears] + [boekplan::match(author:Hans and (tonumber(field:year) or 0) > 2011)] +\stopbuffer + +\cindex{cite} +\tindex{::} + +\typeTEXbuffer \getbuffer + +You can use grouping braces when spaces are involved. Ranges (of numbers) are +recognized. Of course, you can use other characters that the basic alphabet. + +\startbuffer +\cite[authoryears][tugboat::match(author:{Bogusław Jackowski})]\\ +\stopbuffer + +\cindex{cite} +\tindex{::} + +\typeTEXbuffer \getbuffer + +This demonstrates further the interest in converting classical \TEX\ accent +sequences into proper \UTF\ characters. The citations found above \bold{must} +correspond to some bibliography list entries, so we will place this list here: + +\startbuffer +\placebtxrendering [tugboat][criterium=section] +\stopbuffer + +\cindex{placebtxrendering} + +\typeTEXbuffer \getbuffer + +String lookups are partial and case insensitive. + +\startbuffer +\cite [boekplan::match(author:e)]\\ +\cite [boekplan::match(author:h)] +\stopbuffer + +\cindex{cite} +\tindex{::} + +\typeTEXbuffer + +so one must take care in formulating cite queries as both lookups above will +get all five entries: \inlinebuffer, whereas + +\startbuffer +\cite [boekplan::match(author:eg)]\\ +\cite [boekplan::match(author:e*r)] +\stopbuffer + +\cindex{cite} +\tindex{::} + +\typeTEXbuffer + +only finds \inlinebuffer. + +% To Hans: It is curious that match(author:e*r) finds [Hag]en and Br[aslau]. +% To Alan: We match the whole (original) string. + +Note also that the order of the match criteria is not significant. + +\startaside +The search mechanism is very powerful. However, a \bold {major \Index{pitfall}} +or risk comes from the possibility to easily under|-|specify the match criteria. +For example, \TEXcode {match(author:Hagen and author:Hoekwater)} will find \cite +[title] [boekplan::match(title:Fonts)], but it will also find \cite [title] +[boekplan::match(title:Layouts)]; Nor would adding the criterium \TEXcode {and +year:2011} be of any help. The solution is + +\startbuffer +\cite + [authoryear] + [boekplan::match(author:Hagen and author:Hoekwater and title:fonts)] +\stopbuffer + +\cindex{cite} +\tindex{::} + +\typeTEXbuffer \getbuffer + +Note that using \TEXcode {match(title:fonts)} alone would also work, that is +until another reference work containing the word \quote {fonts} in its title gets +added to the dataset! \startfootnote Multiple hits would have occurred in the +examples above containing \TEXcode {title:lua} had only one dataset been used in +the typesetting of the present manual. \stopfootnote Thus, whereas it might +appear that the match mechanism be a more robust way of identifying dataset +entries then short cite \Index {tag}s, incomplete search queries might return +unwanted, excess matches. + +It is quite common in real bibliography databases for some author or authors to +appear in many different references published in the same year, perhaps buried in +a longer list of authors, so some care has to be taken to uniquely identify the +desired work. Of course, this feature can also be a good shorthand as well to +select several different matching works when that is the desired result. +\stopaside + +% This only begins to touch on the search mechanism. +% This section needs to be expanded. + +\stopsection + +\startsection[title=Page index and interaction,reference=sec:index] + +Each citation in the text not only marks the dataset entry for inclusion in the +bibliography list but also records the page number on which the citation occurs. +Each named list rendering can be instructed to include these pages just like an +index. + +\startbuffer +\setupbtxrendering + [default] + [pagestate=start] +\stopbuffer + +\cindex{setupbtxrendering} + +\typeTEXbuffer + +The result can be observed in the \about [ch:biblio] on \at {page} [ch:biblio]. +If interaction is active (\cindex {setupinteraction}\TEXcode +{\setupinteraction[state=start]}), then these page numbers will be \Index +{hyperlink}s back to the citations. If \TEXcode {numbering=yes}, then the +numbered bibliography entries will also contain \Index {hyperlink}s back to the +first occurrence in the text where the entry is cited (which is the same as the +first page indexed). + +% to Hans: Hyperlinks on the list num or APA authoryear is no longer working! +% to Alan: Still? + +Some styles, such as \index {style+APA}\TEXcode {apa}, will have other \Index +{hyperlink}s. The author list including the year will be active just like the +numbers above (an \TEXcode {authoryear} list is usually not numbered). +Furthermore, any doi or url that is included in the entry will be a \Index +{hyperlink} to the external resource. Finally, all titles will contain \Index +{hyperlink}s to the local downloaded file of the cited work if this exists and +was specified (using the data field \TEXcode {file={},}). + +In addition to the index of pages of citations in the text associated with each +entry in the bibliography list, one has the possibility of adding bibliography +items to any standard index list. This can be illustrated through the creation of +a list of authors or names: + +\startbuffer +\defineregister + [indexofauthors] + +\definebtxregister + [authors] + [field=author, + register=indexofauthors, + method=always, + dataset=default, + alternative=invertedshort] +\stopbuffer + +\cindex{defineregister} +\cindex{definebtxregister} + +\typeTEXbuffer + +placed in the preamble of the document and to be followed later, typically +towards the end of the document, by + +\cindex{placeregister} + +\startTEX +\startchapter[title=Index of Names] + \placeregister[indexofauthors][compress=yes] +\stopchapter +\stopTEX + +as can be see in the present manual on \at {page} [ch:indexofauthors]. + +\cindex {definebtxregister} +\showsetup[definebtxregister] + +\cindex {setupbtxregister} +\showsetup[setupbtxregister] + +Any field can be indexed, as desired, for example \TEXcode {field=title}. One +particularly useful field is \TEXcode {keywords={}}: a semi|-|colon separated +list of keywords will be split into individual index entries for each cited work. + +The handling of fields to be interpreted as names (as in \TEXcode {author}) or as +keywords (split into fields separated by semi|-|colons), etc. depends on the +specification and is declared in a lua file associated with the specification +definition file. This will be described in the next chapter. + +\stopsection + +\startsection [title=Summary and explanation of the \TEXcode {\cite} mechanism] + +As the list of cited references is being built in memory, each used dataset entry +is flagged. As the list gets placed, either partially or fully, eventual conflits +in \TEXcode {short} and in \TEXcode {authoryear} tags are resolved through an +assignment of suffixes. These are then fed|-|back to the citation references. + +A dataset can have multiple renderings and multiple datasets and renderings can +be grouped. The many citation variants can be freely used together and this may +or may not make coherent sense. For example, an \TEXcode {authoryear} sorted list +is assigned numbers that are available for use as numbered citation references, +but these numbers will follow the order of the list and not the order of +citations. Conversely, a list that is sorted in the order of citations will still +have \TEXcode {authoryear} and \TEXcode {short} citation tags, but these will be +of less use for the reader in this case than the \TEXcode {authornum} variant. +With such flexibility comes complication. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-completeness.tex b/doc/context/sources/general/manuals/publications/publications-completeness.tex new file mode 100644 index 000000000..5642ea312 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-completeness.tex @@ -0,0 +1,23 @@ +\environment publications-style + +\startcomponent publications-completeness + +\startchapter + [reference=ch:datasetcompleteness, + title={Dataset completeness}] + +\startbuffer +\showbtxdatasetcompleteness[example] +\stopbuffer + +\typeTEXbuffer + +\cindex {showbtxdatasetcompleteness}The listing can be rather long \unknown\ The +header for each entry gives the \TEXcode {index}, \TEXcode {category} and +\TEXcode {tag}. + +\getbuffer + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-contents.tex b/doc/context/sources/general/manuals/publications/publications-contents.tex new file mode 100644 index 000000000..3e5acaa03 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-contents.tex @@ -0,0 +1,18 @@ +\environment publications-style + +\startcomponent publications-contents + +\starttitle[title=Contents] + + \setuplist + [chapter] + [before=, + after=] + + \placelist + [chapter] + [color=black] + +\stoptitle + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-customize.tex b/doc/context/sources/general/manuals/publications/publications-customize.tex new file mode 100644 index 000000000..1a2ab7040 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-customize.tex @@ -0,0 +1,659 @@ +\environment publications-style + +\startcomponent publications-customize + +\startchapter[title=Custom renderings,reference=ch:custom] + +\startsection[title=Introduction] + +The rendering of citations and bibliography lists is highly configurable and +custom rendering schemes can be added. The details can get quite complicated so +we will begin with a description of how citation variations can be used in the +running text, followed by a description on how to control the rending of the +associated bibliography list. + +\startaside +Loading the specification file defines a \Index {namespace}, say \TEXcode {apa}, +containing subspaces \TEXcode {apa:list} and \TEXcode {apa:cite} as well as +variants, for example \TEXcode {apa:cite:authoryear}, allowing \emphasis +{parameters} to be tuned independently for each form. This insures independence +but can get somewhat confusing. Most users will not encounter any problems as all +of this setup work is taken care of in the specification file; only those needing +to fine|-|tune specific settings need to better understand the underlying +mechanism. + +The rendering of the variants can be adjusted through \Cindex {setupbtx} in the +appropriate \Index {namespace}, for example modifying (or suppressing) +parenthesis or activating or deactivating interaction \Index {hyperlink}s. Beyond +the settings of parameters in the appropriate \Index {namespace}, +\emphasis{setups} are used to perform the actual renderings of citations as well +as of lists. One must be aware of \Index {namespace} \Index {isolation} and +\Index {inheritance} as well as fall|-|back when attempting to make changes. + +When small modifications on one of the pre|-|defined specifications are desired, +we suggest loading the specification and then adjusting certain parameters and +overloading the appropriate setups. Eventually, a new specification might be +necessary. +\stopaside + +A common setup will enable or disable interaction: + +\startbuffer +\setupbtx [interaction=start] +\stopbuffer + +\cindex{setupbtx} + +\typeTEXbuffer + +Notice that this is applied to the root \Index {namespace}. + +Other root|-|\Index {namespace} parameters that have been used are \TEXcode +{specification}, \TEXcode {dataset} and \TEXcode {numbering}. + +Associated with \TEXcode {specification} is an additional parameter \TEXcode +{default=} that defines a fall|-|back specification to be used to complete a +derived specification. \startfootnote For example, a variant on a specification +can be defined by only addressing specific differences, for example \index +{style+RMP}\TEXcode {specification=rmp} would be associated with \index +{style+APS}\TEXcode {default=aps}, as this describes a style used by the journal: +The Review of Modern Physics, mostly based on the style of the American Physical +Society. \stopfootnote + +Further \quote {low|-|level} formatting parameters, mostly dealing with the +formatting of names, are also defined by default in the root namespace. These are +listed in \in {table} [tab:setupbtx]. Some might eventually be redefined by the +specification in other namespaces, and may with good reason differ by context: +between the \TEXcode {[cite]} and \TEXcode {[list]} namespaces, for example. + +In order to insure the independence of specifications, each one defines its own +root namespace, for example \TEXcode {[default]}, \TEXcode {[apa]} or \TEXcode +{[aps]}, inheriting its settings from root, upon which are built the other +namespaces. + +\startplacetable + [reference=tab:setupbtx, + list={\TEXcode {\setupbtx} low|-|level formatting parameters}, + title={\Cindex {setupbtx} low|-|level formatting parameters. Some may be + redefined differently in the \TEXcode {cite} and \TEXcode {list} namespaces.}] +\starttabulate [|Tr|Tl|p|] + \NC specification \NC default \NC default style \NC \NR + \NC default \NC <null> \NC fall|-|back style \NC \NR + \NC interaction \NC start \NC active hyperlinks \NC \NR + \NC separator \NC \Cindex{btxsemicolon} \NC between multiple references \NC \NR + \NC separator:firstnames \NC \Cindex{btxspace} \NC between first names \NC \NR + \NC separator:juniors \NC \Cindex{btxspace} \NC before \quote{juniors} \NC \NR + \NC separator:vons \NC \Cindex{btxspace} \NC before \quote{vons} \NC \NR + \NC separator:initials \NC \Cindex{btxspace} \NC between initials \NC \NR + \NC stopper:initials \NC . \NC initialization truncation symbol \NC \NR + \NC separator:invertedinitials \NC \Cindex{btxcomma} \NC before initials, inverted form \NC \NR + \NC separator:invertedfirstnames \NC \Cindex{btxcomma} \NC before first names, inverted form \NC \NR + \NC authorconversion \NC normal \NC normal, normalshort, inverted, invertedshort, name (see \in{table}[tab:authorconversion]) \NC \NR + \NC monthconversion \NC number \NC month, month:mnen (see \TEXcode {\convertnumber}) \NC \NR + \NC journalconversion \NC normal \NC normal, abbreviated(short?) \NC \NR + \NC etallimit \NC 3 \NC length of author list \NC \NR + \NC etaldisplay \NC 3 \NC length of truncated author list \NC \NR + \NC \tindex{others}otherstext \NC et al. \NC author list truncation text \NC \NR + \NC separator:names:2 \NC \Cindex{btxcomma} \NC separates multiple names \NC \NR + \NC separator:names:3 \NC \Cindex{btxcomma} \NC before last name in a list \NC \NR + \NC separator:names:4 \NC \Cindex{btxcomma} \NC between only two names \NC \NR + \NC separator:2 \NC \Cindex{btxsemicolon} \NC separates multiple objects \NC \NR + \NC separator:3 \NC \Cindex{btxsemicolon} \NC before last object in a list \NC \NR + \NC separator:4 \NC \Cindex{btxsemicolon} \NC between only two objects \NC \NR +\stoptabulate +\stopplacetable + +\cindex {setupbtx} +\showsetup[setupbtx] + +\stopsection + +\startsection + [reference=sec:customcite, + title=Custom citation renderings] + +\startsubsubject [title=Parameters] + +Citation variants are mostly controlled though adjustment of their parameters +within the appropriate \Index {namespace}. For example, the cite variant \cindex +{cite}\TEXcode {\cite[num]} would be addressed through + + +\cindex {setupbtx} + +\startTEX +\setupbtx[default:cite:num] +\stopTEX + +for the \TEXcode {default} specification, or alternately, through + +\cindex {setupbtx} + +\startTEX +\setupbtx[apa:cite:num] +\stopTEX + +for the \index {style+APA}\TEXcode {apa} specification. For example, superscript +numbered citations in the \index {style+APS}\TEXcode {aps} specification could be +obtained through + +\cindex{setupbtx} + +\startTEX +\setupbtx[aps:cite:num][command=\high] +\stopTEX + +Typical parameters (in addition to those listed in \in {table} [tab:setupbtx]) +are presented in \in {table} [tab:setupbtxcite]. + +\startplacetable + [reference=tab:setupbtxcite, + location=force, + list= {\TEXcode{\setupbtx [cite]} parameters}, + title={\cindex{setupbtx}\TEXcode{\setupbtx[cite]} parameters}] +\starttabulate [|Tr|l|l|] +\NC alternative \NC num \NC default cite form \NC \NR +\NC left \NC \NC opening string \NC \NR +\NC right \NC \NC closing string \NC \NR +\NC inbetween \NC \Cindex{btxspace} \NC \NC \NR +\NC range \NC \TEXcode{\endash} \NC \NC \NR +\NC command \NC \NC \NC \NR +\NC style \NC \NC \NC \NR +\NC sorttype \NC normal \NC \NC \NR +\NC compress \NC yes \NC \NC \NR +\stoptabulate +\stopplacetable + +A demonstration of how these parameters can be manipulated in an individual +\TEXcode {\cite} call is shown in \in{table} [tab:authorconversion], which also +illustrates the different ways of formatting names. + +\startplacetable + [title={\TEXcode{authorconversion}}, + reference=tab:authorconversion] +\starttabulate [|Tl|p|] +\NC ac \NC \TEXcode{\cite[alternative=author,etallimit=,authorconversion=ac][article]} \NC \NR +\HL +\NC name \NC \cite[alternative=author,etallimit=,authorconversion=name] [article] \NC \NR +\NC normal \NC \cite[alternative=author,etallimit=,authorconversion=normal] [article] \NC \NR +\NC normalshort \NC \cite[alternative=author,etallimit=,authorconversion=normalshort] [article] \NC \NR +\NC inverted \NC \cite[alternative=author,etallimit=,authorconversion=inverted] [article] \NC \NR +\NC invertedshort \NC \cite[alternative=author,etallimit=,authorconversion=invertedshort][article] \NC \NR +\stoptabulate +\stopplacetable + +\stopsubsubject + +\startsubsubject [title=Setups] + +The next step in the customization of citation variants is through the overlaying +of setups that handle the actual rendering of the citation. These rarely will +need to be changed as most tuning can be done through the adjustment of +parameters such as those given above. \startfootnote An exception is for special +features, such as in the \index {style+APA}\TEXcode {apa} specification where a +missing date is replaced by the notation \quotation {n..d.}. \stopfootnote + +It is to be pointed|-|out that original citation variants can be easily added. As +an example, imagine that one might like to access the field \TEXcode {abstract} +that is normally not rendered (like many other unused dataset fields). One would +start by defining a parameter \Index {namespace} inheriting from the \TEXcode +{cite} \Index {namespace}, followed by a simple setup (remember that the \TEXcode +{apa} specification is currently active): + +\startbuffer +\definebtx[apa:cite:abstract][apa:cite] +\startsetups btx:apa:cite:abstract + \btxcitereference + \btxflush{abstract} +\stopsetups + +\startparagraph [style=slanted] +\cite[abstract][boekplan::Hagen2010metafun] +\stopparagraph +\stopbuffer + +\cindex{definebtx} +\cindex{btxcitereference} +\cindex{btxflush} +\cindex{cite} +\cindex{startsetups} +\cindex{stopsetups} +\tindex{::} + +\typeTEXbuffer + +\getbuffer + +If no special manipulation is known, the field with the same name (if found) will +be simply flushed. This will only work, however, if the field is identified as +either required or optional, that is not flagged as ignored in \in {table} +[tab:fields] (see also \in {Appendix} [ch:datasetfields]). For the sake of the +present manual, the field \BTXcode{abstract} has been defined as optional for the +\BTXcode{book} entry in the specification's lua file. + +But don't expect too much support for such low|-|level rendering control. + +\stopsubsubject + +\stopsection + +\startsection[title=Custom list renderings,reference=sec:list] + +The rendering of lists is much more flexible and configurable than the rendering +of citation markers. This is because the nature of data to be rendered requires +many tools and helpers to deal with all of the eventual contingencies inherent in +describing bibliographical references. + +The same \quote {low|-|level} formatting parameters used for citations also apply +for \TEXcode {list} \Index {namespace}s, although their settings may differ from +those of the citations. Consider the \index {style+APA}\TEXcode {apa} style that +specifies the use of \tindex {others} \quotation {et al.} in citations but +\quotation {\textellipsis} in the bibliography list, \quotation {and} in +citations but \quotation {\textampersand} in lists, last names only in \TEXcode +{authoryear} citations, etc. + +\startsubsubject[title=Bibliographies as lists] + +At another level of detail, the bibliography list is rendered in a standard +\CONTEXT\ list environment that can be setup using the command \Cindex +{setupbtxlist} (which is only \Cindex {setuplist} working in the protected +bibliography environment: \TEXcode {btx}). The root settings, appropriate for a +numbered bibliography list, are: + +\cindex{setuplist} + +\startTEX +\setuplist + [btx] + [prefixstopper=:, + state=start, + alternative=a, + before=\blank, + after=\blank] +\stopTEX + +whereas an unnumbered, author|-|year sorted list might have: + +\cindex{setupbtxlist} + +\startTEX +\setupbtxlist + [apa] + [alternative=paragraph, + margin=3\emwidth] +\stopTEX + +as already seen in \in {Chapter} [ch:renderings]. The above demonstrate that +\cindex {setupbtxlist}\TEXcode {\setupbtxlist[name]} is just a synonym for +\cindex {setuplist}\TEXcode {\setuplist[btx:name]}. + +\cindex {setupbtxlist} +\showsetup[setupbtxlist] + +\cindex {setuplist} +\showsetup[setuplist] % too big for the page! + +Each specification will have its own list \Index {namespace} (\TEXcode +{btx:specification}) that inherits from the root \TEXcode {btx} \Index +{namespace}. This model of inheritance holds true for the citation and list +details as described earlier. + +\stopsubsubject + +\startsubsubject[title=Setups] + +The layout of the information presented in the list is entirely controlled +through setups, with the help of some underlying \LUA\ code organizing the data +stored in the dataset. These setups rely on further setups as well as some +convenient helpers or defined special commands. To understand this, consider as +an illustration the setups defined for the \TEXcode {default} specification +(taken from the source file \type {publ-imp-default.mkvi}): + +\cindex{startsetups} +\cindex{stopsetups} +\cindex{texdefinition} +\cindex{btxperiod} + +\startTEX +\startsetups btx:default:list:book + \texdefinition{btx:default:author} + \texdefinition{btx:default:title} + \texdefinition{btx:default:editionset} + \texdefinition{btx:default:publisher} + \texdefinition{btx:default:year} + \btxperiod +\stopsetups +\stopTEX + +\cindex{startsetups} +\cindex{stopsetups} +\cindex{texdefinition} +\cindex{btxperiod} + +\startTEX +\startsetups btx:default:list:article + \texdefinition{btx:default:author} + \texdefinition{btx:default:title} + \texdefinition{btx:default:journal} + \texdefinition{btx:default:year} + \btxperiod +\stopsetups +\stopTEX + +This specification could be extended to handle publication categories other than +\TEXcode {book} and \TEXcode {article} simply by defining an additional setup, +\emphasis {almost} (see the following). + +\stopsubsubject + +\startsubsubject[title=\LUA\ tables] + +The qualification above is to bring attention to an important \LUA\ component +that is defined in a companion source file: \TEXcode {publ-imp-default.lua}. This +file defines a hierarchical \LUA\ table containing an element \TEXcode +{categories} that itself contains the entries \TEXcode {book}, \TEXcode +{article}, etc. The entries for each \Index {category} themselves contain the +entries \index {field+required}\TEXcode {required} and \index +{field+optional}\TEXcode {optional} listing the dataset fields that are to be +used. Any field that is not declared either \index {field+required}required or +\index {field+optional}optional will be \index {field+ignored}\emphasis +{ignored}. \startfootnote The difference between \index {field+required}\quote +{required} and \index {field+optional}\quote {optional} is only a question of +diagnostics as described in the Appendices. Their functional meaning is rather +\quote {handled} in contrast to \index {field+ignored}\quote {ignored}. +\stopfootnote Note that if a category is \emphasis {not} declared in this \LUA\ +table, than \emphasis {all} of its fields will be considered \index +{field+optional}\quote {optional}. Thus, ignoring this level of control and +simply defining additional setups might be sufficient for most use. + +The advantage of the \LUA\ table is a great simplification of the logic of the +helper setups. Fields that might be irrelevant for one category yet used in +another can be tested; if the field is to be \index {field+ignored}\quote +{ignored}, than a fetch will return nothing. Indeed, the above two setups could +be replaced by a single setup as \TEXcode {journal} is irrelevant and thus +ignored for the \Index {category} \TEXcode {book} but not for the \Index +{category} \TEXcode {journal}. However, an oversimplification such as just +described would be rather confusing and would not extend well to a more complete +specification (such as \index {style+APA}\TEXcode {apa}) handling many different +categories. + +Note, as well, that fields \index {field+ignored}\quote {ignored} for certain +\index {category}categories in the bibliography list will also be ignored in +citations. For example, choosing to ignore \TEXcode {title} in some \Index +{category}, say \TEXcode {article}, will cause \TEXcode {\cite[title]} to fail +(return nothing) when referring to an entry of that category. In the example +shown in \in {section} [sec:customcite], the abstract field would not return +anything if it did not appear in the \LUA\ table. + +This \LUA\ table also defines (as \index {type}\quote {types}, outside of \index +{category}\quote {categories}) what fields are to be interpreted as names, what +fields are to eventually be interpreted as a number or range of numbers, and what +fields are to be interpreted specially as a (semi|-|colon) separated list (for +example, \TEXcode {keywords}). + +A more subtle feature of the \LUA\ level is the notion of \index {set}\quote +{sets}. Related fields can be grouped into sets, for example. + +\startLUA +book = { + sets = { + author = { "author", "editor", }, + editionset = { "edition", "volume", "number" }, + }, +}, +\stopLUA + +A fetch of the set \text {author} (i.e. \cindex {btxflush}\TEXcode +{\btxflush{author}}, to be described below) will return the \text {author} field +if this is present, otherwise it will return the \TEXcode {editor} field, for an +edited book, for example. Testing for the presence of a set in a data entry is +equivalent to a logical \emphasis{or} in testing for the presence of each element +of the set. This mechanism can appear confusing yet it has served to greatly +simplify the logic of the various setups. \startfootnote Sometimes a \Index {set} +will be defined using the same name as its first element, sometimes it can be +given a unique name (typically ending in \quote {set}). \stopfootnote + +The \TEXcode {author} set is a bit special given its use in the \TEXcode +{authoryear(s)}, \TEXcode {authornum}, and \TEXcode {short} citation variants. +This \Index {set} determines what fields are to enter into the citation \Index +{tag}s, a generalization of the notion of author. For example, in the \index +{style+APA}APA style, this set would include the author, editor, or title fields +or an article and the author, editor, publisher, or title fields for a book and +still other sequences of fields for other categories of publications. + +\stopsubsubject + +\startsubsubject[title=Defined helpers] + +Fetching data from the dataset is performed using the command encountered above: +\TEXcode {\btxflush}. If the field (or no elements of the set) is not found, then +this command will return nothing. + +\cindex {btxflush} +\showsetup[btxflush] + +Alternately, one might need to explicitly test for the presence or absence of the +field, in order to conditionally include punctuation or not to trigger +separators, for example. Three test macros have been defined: + +\startplacetable [title=Conditional macros] +\cindex{btxdoifelse} +\cindex{btxdoif} +\cindex{btxdoifnot} +\startTEX +\btxdoifelse{fieldname}{action when found}{action when not found} +\btxdoif {fieldname}{action when found} +\btxdoifnot {fieldname} {action when not found} +\stopTEX +\stopplacetable + +In many cases, the readability can be improved by using further setups, for +instance: + +\cindex{btxdoifelse} +\cindex{fastsetup} + +\startTEX +\btxdoifelse {author} { + \fastsetup{btx:apa:author:yes} +} { + \fastsetup{btx:apa:author:nop} +} +\stopTEX + +Note that the choice between using setups (defined through \Cindex {startsetups} +\unknown\ \Cindex {stopsetups} and recalled through \Cindex {fastsetup}) versus +textdefinitions without arguments (defined through \Cindex {starttexdefinition} +\unknown\ \Cindex {stoptexdefinition} and recalled through \Cindex +{texdefinition}) is a question of taste and opportunity. One should keep in mind +not get carried away abusing setups and texdefinitions for simple code fragments +that are to be used uniquely. + +An extra conditional is available for testing interactivity: + +\cindex{btxdoifelseinteraction} + +\startTEX +\btxdoifelseinteraction{action when true}{action when false} +\stopTEX + +There is also a conditional \Cindex {btxinteractive} which is more efficient, +although in practice efficiency is not so important here. + +\blank + +In addition to \Index {set}s, there are derived or special fields such as +\TEXcode {num} (for the reference number), \TEXcode {suffix} (to be appended in +some cases to \TEXcode {year}), \TEXcode {short} (for names), etc. These all can +be retrieved using \Cindex {btxflush}. Sometimes one might want to force access +to a particular data field (such as \TEXcode {author}) rather than eventually an +element of a \Index {set} having the same name. There are three basic commands to +flush data and a few others to flush associated information: + +\startplacetable [title=Field access macros] +\starttabulate[|l|l|] +\NC \Cindex{btxflush} \NC fetch a derived or explicit field \NC \NR +\NC \Cindex{btxdetail} \NC fetch a derived field (e.g.\ \TEXcode {short}) \NC \NR +\NC \Cindex{btxfield} \NC fetch a explicit field (e.g.\ \TEXcode {year}) \NC \NR +\NR +\NC \Cindex{btxfieldname} \NC fetch the field name \NC \NR +\NC \Cindex{btxfieldtype} \NC fetch the field type (e.g.\ \TEXcode{author}, \TEXcode{range}, \unknown \NC \NR +\NC \Cindex{btxfoundname} \NC fetch the field name of a set (or field) \NC \NR +\NC \Cindex{btxfoundtype} \NC fetch the field type of a set (or field) \NC \NR +\stoptabulate +\stopplacetable + +A few helpers are provided to inject symbols but also take care of leading and +trailing spaces: \startfootnote These make use of the \CONTEXT\ command \Cindex +{removeunwantedspaces}. There is also a \quote {secret} command \TEXcode +{\removepunctuation} that can be quite useful, but also lead to undesired +consequences when wielded blindly! \stopfootnote + +\startplacetable [title=Punctuation macros] +\starttabulate[|||] +\NC \Cindex{btxspace} \NC before \btxspace after \NC \NR +\NC \Cindex{btxnbsp} \NC before \btxnbsp after \NC \NR +\NC \Cindex{btxnobreakspace} \NC before \btxnobreakspace after (same as \Cindex {btxnbsp}) \NC \NR +\NC \Cindex{btxperiod} \NC before \btxperiod after \NC \NR +\NC \Cindex{btxcomma} \NC before \btxcomma after \NC \NR +\NC \Cindex{btxcommabreak} \NC before \btxcommabreak after (allows a line break) \NC \NR +\NC \Cindex{btxleftparenthesis} \NC before \btxleftparenthesis after \NC \NR +\NC \Cindex{btxrightparenthesis} \NC before \btxrightparenthesis after \NC \NR +\NC \Cindex{btxrightparenthesiscomma} \NC before \btxrightparenthesiscomma after \NC \NR +\NC \Cindex{btxrightparenthesisperiod} \NC before \btxrightparenthesisperiod after \NC \NR +\NC \Cindex{btxleftbracket} \NC before \btxleftbracket after \NC \NR +\NC \Cindex{btxrightbracket} \NC before \btxrightbracket after \NC \NR +\NC \Cindex{btxrightbracketcomma} \NC before \btxrightbracketcomma after \NC \NR +\NC \Cindex{btxrightbracketperiod} \NC before \btxrightbracketperiod after \NC \NR +\stoptabulate +\stopplacetable + +\stopsubsubject + +\starthiding + +Normally you can use \TEXcode {\btxfield} or \TEXcode {\btxflush} as derived +fields just like analyzed author fields are flushed in a special way. There is +experimental support for so called manipulators. You can for instance say this: + +\starttyping +\btxflush{lowercase->title} +\stoptyping + +A sequence of manipulators is applied to fetched field, where a sequence is one +or more manipulators: + +\starttyping +\btxflush{stripperiod->uppercase->title} +\stoptyping + +Some actions are recognized (built|-|in) but you can also use actions from other +namespaces, like in: + +\starttyping +\btxflush{converters.Word -> title} +\stoptyping + +Watch how we can use spaces around the \TEXcode {->} which is nicer for wrapped +around usage. Eventually, we might put some more function in the default +namespace. + +So, the previous example setup can be rewritten as: + +\starttyping +\btxdoif {title} { + \bold{\btxfield{title}} + \btxcomma +} +\stoptyping + +There is a special command for rendering a (combination) of authors: + +\starttyping +\btxflushauthor{author} +\btxflushauthor{editor} +\btxflushauthor[inverted]{editor} +\stoptyping + +Instead of the last one you can also use: + +\starttyping +\btxflushauthorinverted{editor} +\stoptyping + +You can use a (configurable) default or pass directives: Valid directives are + +\starttabulate +\NC \bf conversion \NC \bf rendering \NC \NR +\HL +\NC \TEXcode{inverted} \NC the Frog jr, Kermit \NC \NR +\NC \TEXcode{invertedshort} \NC the Frog jr, K \NC \NR +\NC \TEXcode{normal} \NC Kermit, the Frog, jr \NC \NR +\NC \TEXcode{normalshort} \NC K, the Frog, jr \NC \NR +\stoptabulate + +The list itself is not a list in the sense of a regular \CONTEXT\ structure +related list. We do use the list mechanism to keep track of used entries but that +is mostly because we can then reuse filtering mechanisms. The actual rendering of +a reference and entry runs on top of so called constructions (other examples of +constructions are descriptions, enumerations and notes). + +\showsetup[setupbtxlist] + +You need to be aware what command is used to achieve the desired result. For +instance, in order to put parentheses around a number reference you say: + +\starttyping +\setupbtxlistvariant + [num] + [left=(, + right=)] +\stoptyping + +If you want automated width calculations, the following does the trick: + +\starttyping +\setupbtxrendering + [default] + [width=auto] +\stoptyping + +but if you want to control it yourself you say something: + +\starttyping +\setupbtxrendering + [width=none] + +\setupbtxlist + [default] + [width=3cm, + distance=\emwidth, + color=red, + headcolor=blue, + headalign=flushright] +\stoptyping + +In most cases the defaults will work out fine. + +Normally the references are numbered using one counter for the whole document. If +you want each list to have its own number, then you can set the \TEXcode +{continue} parameter: + +\starttyping +\setupbtxrendering[continue=no] +\stoptyping + +In a similar fashion you can influence if references are included only once of in +each list: + +\starttyping +\setupbtxrendering[repeat=yes] +\stoptyping + +\stophiding + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-database.tex b/doc/context/sources/general/manuals/publications/publications-database.tex new file mode 100644 index 000000000..13663b1b5 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-database.tex @@ -0,0 +1,538 @@ +\environment publications-style + +\startcomponent publications-database + +\startchapter[title=The database] + +The bibliography subsystem uses a database (or a set of databases) to construct a +list of citations to be used in a scholarly work. However, it will be shown later +that the database system can be used (and abused) to many ends having little or +nothing at all to do with citations and bibliographies. Nevertheless, at first we +shall remain focused on the use of bibliography databases. + +The data to be used must have a source and a structure. In the next sections we +describe the possible input. + +\startsection[title=\BibTeX] + +The \BIBTEX\ format is rather popular in the \TEX\ community and even with its +shortcomings it will stay around for a while. Many publication websites can +export and many tools are available to work with this database format. It is +rather simple and looks a bit like \index [LUA table] {\LUA\ table}\LUA\ tables. +Indeed, it is said that the \BIBTEX\ format was one of the inspirations for the +constructor syntax in \LUA\ \cite [alternative=num, +righttext={\btxcomma Chapter\nbsp 12.}] [default::Ierusalimschy2006]. + +Unfortunately the content can be (and usually is) polluted with +non|-|standardized \TEX\ commands which complicates pre- or post|-|processing +outside \TEX. In that sense a \BIBTEX\ database is often not coded neutrally. +Some limitations, like the use of commands to encode accented characters root in +the \ASCII\ world and can be bypassed by using \index [UTF] {\UTF}\UTF\ instead +(as handled somewhat in \LATEX\ through extensions such as \Tindex {bibtex8}). + +The normal way to deal with a bibliography is to refer to entries using a unique +\Index {tag} or key. When a text containing a list of entries is typeset, this +reference can be used for linking purposes. The list can be processed and sorted +using the \Tindex {bibtex} program that converts the database into something more +\TEX\ friendly (a \Tindex {.bbl} file). + +In \CONTEXT\ we no longer use the (external) \goto {\Tindex{bibtex} program} +[url(https://www.ctan.org/pkg/bibtex)] at all: we simply parse the database files +and deal with the necessary manipulations directly in \CONTEXT. One or more such +databases can be used and combined with additional entries defined within the +document. We can have several such datasets active at the same time. + +\startaside +\emphasis {On the name \Tindex{btx}:} many of the \CONTEXT\ commands that will be +used in the following contain the label \TEXcode {btx} in their name. This +identifier was retained despite the fact that \CONTEXT\ \MKIV\ is now completely +independent of \BIBTEX; it reflects the role still played by \BIBTEX\ data as a +preferred source format and serves as a handy, unique identifier, both internally +in the programming as well as for the user. This three|-|letter label is +systematically used in commands that otherwise attempt to avoid cryptic|-|styled +names. +\stopaside + +A \BIBTEX\ file entry looks like this: + +\startBTX +@Article {sometag, + author = "An Author and Another One", + title = "A hopefully meaningful title", + journal = maps, + volume = "25", + number = "2", + pages = "5--9", + month = mar, + year = "2013", + ISSN = "1234-5678", +} +\stopBTX + +Entries are of the form: \index {category}\BTXcode {@category{...}} + +Anything outside of a valid \BTXcode {@category{...}} construction is ignored and +is taken to be a comment. Within an entry, there are to be no comments but one +can prefix field names, for example, to have them ignored. + +There is a special entry type named \index {@comment}\BTXcode {@comment{...}}. +The main use of such an entry type is to comment a large part of the bibliography +easily, since anything outside an entry is already a comment, and commenting out +one entry may be achieved by just removing its initial~\BTXcode {@}. — The \index +{@comment}\BTXcode {@comment{...}} entry is perhaps of some use, although this is +not very elegant! As one can input multiple bibliography data files, as will be +seen below, it is much better practice to split datafiles for optional loading. + +Many \BIBTEX\ data management tools such as \Tindex {jabref} (see below) will +ignore and then throw|-|away all such handily|-|crafted comments and data entries +turned into comments. So one must beware! + +The field names are all cast to lowercase so capitalization is irrelevant; +Spacing is not important and should be used advantageously for readability. The +leading \Index {tag} (\BTXcode {sometag} in the example above) cannot contain +spaces and \emphasis {must} be followed by a comma. + +The entry \Index {tag} (\BTXcode {@category{sometag,...}}) is not to be confused +with the optional field \BTXcode {key=sortkey,} that may also be present. + +Normally a value is given between quotes (or curly brackets) but single words are +also valid (as there is no real benefit in not using quotes or curly brackets, we +advise to always use them, contrary to our example above). The order of the +fields in an entry is inconsequential and there can be many more fields than +those shown above. Instead of string values one can also use predefined +shortcuts. The title for example might quite often contain \TEX\ macros, and some +fields, like \BTXcode {pages} have funny characters such as the endash (typically +entered as \BTXcode {--}) so we have a mixture of data and typesetting +directives. Furthermore, if you are covering non||English references, you often +need characters that are not in the \ASCII\ subset. Note that \CONTEXT\ is quite +happy with \UTF, but if your database file uses old|-|fashioned \TEX\ accent +combinations then these will be internally converted automatically to \UTF. + +Commands (macros) found in a database file are converted to an indirect call, +which is quite robust. The use of commands in the database file will be described +in \in {section} [sec:Commands]. + +The \Tindex {author} (and \Tindex {editor}) fields are parsed separating multiple +authors identified by the conjunction \quote{and}. Each name is assumed to be in +the form: + +\definetyping + [NameSyntax] + [margin=1em] + +\startNameSyntax +Firstname(s) Lastname +\stopNameSyntax + +\seeindex {vons} {particle} + +where \type {Lastname} is a single word but may include an optional (nobility) +\Index {particle}: lower|-|case word(s) such as \quotation {von}, \quotation +{de}, \quotation {de la}, etc.) \emphasis {unless} specifically in the two- or +three|-|token form: + +\index{suffix} + +\startNameSyntax +Lastname(s), Firstname(s) +Lastnames(s), Suffix(es), Firstname(s) +\stopNameSyntax + +separated explicitly using comma(s) thus allowing multi|-|word \type {Lastnames}. + +\startaside +An \BTXcode {author} field is sometimes abused in traditional \BIBTEX\ usage to +hold not a name but rather an entity. Other fields, such as \BTXcode +{organization} or \BTXcode {collaboration}, for example, should be used in such +cases. +\stopaside + +\BIBTEX\ also (obscurely) supports the syntax: + +\seeindex{juniors}{suffix} +\index{suffix} + +\startNameSyntax +Firstname(s) \{Lastname(s), Suffix(es)\} +\stopNameSyntax + +we may (or may not) support this in the future, so don't use this! + +We extend \BIBTEX\ by optionally parsing each name in terms of four or five +tokens: + +\index{particle} \index{suffix} \index{initial} + +\startNameSyntax +Particule(s), Lastname(s), Suffix(es), Firstname(s) +Particule(s), Lastname(s), Suffix(es), Firstname(s), Initial(s) +\stopNameSyntax + +in order to allow a free form for the particules, irrespective of capitalization, +thus avoiding the need to resort to any sort of \TEX\ trickery \cite [num] +[default::Patashnik1988,Markey2009]. In fact, an optional sixth token is parsed +whose meaning is presently reserved for future directives describing how the name +is to be interpreted: + +\index{particle} \index{suffix} \index{initial} + +\startNameSyntax +Particule(s), Lastname(s), Suffix(es), Firstname(s), Initial(s), directives +\stopNameSyntax + +\BIBTEX\ additionally accepts the special token \Tindex {others} to be used +(sparingly) to indicate an incomplete author list. Note that most style +specifications will handle the truncation of long author lists in a systematic +fashion. The \index [others] {\tt and others}\BTXcode {and others} construction +finds its use when the complete author list is not well known or ill|-|defined. + +Fields other than \Tindex {author} and \Tindex {editor}, for example \Tindex +{artist} or \Tindex {director} if one desires, can be declared to be of type +\quote {author} and thus interpreted as names, but this is a subject for +specialists. + +The \BTXcode {keywords} field can also be split into tokens separated by +semicolons (keyword; keyword; \unknown). This can be useful, as will be seen +later, in the creation of keyword indexes, for example. + +Other string values such as \BTXcode {title} are kept literally (except for an +internal automatic conversion to \UTF\ of certain \TEX\ strings such as accent +combinations, endash, quotations, etc.). Note that the bibliography rendering +style (see below) might specify a capitalization of the title (using the +\CONTEXT\ commands \TEXcode {\Word} or \TEXcode {\Words}, for example). +Capitalized Names and acronyms are respected removing a need for the \BIBTEX\ +practice of \quote{protecting} such words or letters with surrounding curly +brackets (which here are simply stripped off). (Furthermore, since \CONTEXT\ uses +\UTF, it does not suffer from all of the complicated \Index {sorting} issues that +plague \BIBTEX|/|\LATEX.) As some styles might not specify the capitalization of +words in the title whereas other styles might, it is recommended that strings be +written in lower case except where upper case is explicitly required so as to be +compatible with all such capitalization styles. + +\startaside +Some bibliographic database sources can be quite sloppy and return strings +(titles and even authors) in all capitals, for example. We have made the design +choice \emphasis {not} to follow the \BIBTEX\ practice/feature of explicitly +formatting all string values, as we did not want to require the protection +through enclosing curly brackets that would have been a necessary consequence. +Thus, some cleaning of these database files might be needed. Furthermore, we +attempt to use all the power of \CONTEXT\ and \LUA, thus making unnecessary much +(most?) of the \TEX-like encoding of the data. We encourage users to clean|-|up +their \Tindex{.bib} database files as much as possible so that they contain only +the necessary data, with a minimum of explicit formatting directives. +\stopaside + +String values, as described above, can be enclosed indifferently between matching +curly brackets: \BTXcode {{}} or pairs of quotation marks: \BTXcode {""}. +Multiple string values can be \index {string concatenation}concatenated using the +operator \BTXcode {\#}, as will be illustrated in \in {table} +[tab:mkiv-publications.bib]. + +Everything outside of a valid entry is ignored and treated as a \Index {comment}. +Syntactic errors (such as a missing comma or some unbalanced quotes or +parenthesis) are also skipped over, i.e. ignored. This is to attempt to continue +on to valid data but may lead to unexpected results. It is therefore the user's +responsibility to insure the correctness of the data files. Whereas some checks +and warnings are issued, the system is purposefully not too verbose. + +Data is handled on a \quote {first come, first served} basis: duplicate \index +{duplicate+fields}\emphasis {fields} in an entry are ignored \startfootnote Note +that some \BIBTEX\ practice allows for the concatenation of duplicate name \index +{duplicate+fields}fields (i.e. \BTXcode {author} and \BTXcode {editor}) through +\BTXcode {and}, but (silently) ignores duplicate other fields. We choose to have +a consistant behavior and disallow duplicate field occurrences. \stopfootnote +though duplicate \index {duplicate+entries}\emphasis {entries} (having the same +\index{duplicate+tags}tag) are retained, but the subsequent identical \Index +{tag}s will be modified by adding a suffix $-n$ for the $n$\high {th} duplicate. +The presence of duplicate \index {duplicate+fields}fields or \index +{duplicate+tags}tags will be flagged as such with warnings in the log file. +Duplicate \index {duplicate+entries}entries using different \Index {tag}s will +not be treated as duplicates. + +A special provision has been made to declare author \Index {synonyms}, that is +names that might occur with a variation of spellings or aliases. This shall be +discussed later. + +We have attempted to remain compatible with the \BIBTEX\ format, and any new +bibliography extensions that we introduce here were designed in a way to remain +compatible with \BIBTEX, being simply ignored rather than potentially generating +a \BIBTEX\ error. + +The \BIBTEX\ files are loaded in memory as \LUA\ table but can be converted to +\XML\ so that we can access them in a more flexible way, but that is another +subject for specialists. + +\stopsection + +\startsection [reference=sec:Commands,title=Commands in entries] + +One unfortunate aspect commonly found in \BIBTEX\ files is that they may contain +\TEX\ commands. Even worse is that there is no standard on what these commands +can be and what they mean, at least not formally, as \BIBTEX\ is a program +intended to be used with many variants of \TEX\ style: plain, \LATEX, and others. +This means that we need to define our use of these typesetting commands. (In +particular, one might need to redefine those that are too \LATEX|-|centric.) +However, in most cases, they are just abbreviations or font switches and these +are often well known. Therefore, \CONTEXT\ will try to resolve them before +reporting an issue. The log file will announce the commands that have been seen +in the loaded databases. For instance, loading \Tindex{tugboat.bib} (distributed +with \TEXLIVE) gives a long list of commands of which we show a small set of the +five most frequently encountered ones here: + +\startbuffer +\definebtxdataset[tugboat] +\usebtxdataset[tugboat][tugboat.bib] +\stopbuffer + +\getbuffer + +\starttyping +publications > tugboat tt 134 known +publications > tugboat Dash 136 unknown +publications > tugboat acro 137 known +publications > tugboat LaTeX 209 known +publications > tugboat TeX 856 known +\stoptyping + +Some are flagged as known and others as unknown. You can define unknown commands, +or overload existing definitions in the standard way (\emphasis{e.g.} \TEXcode +{\def\Dash{—}}), the \CONTEXT\ way (\TEXcode {\define\Dash{—}}) or, +alternatively, in the following way: + +\cindex{definebtxcommand} + +\startTEX +\definebtxcommand\TUB {TUGboat} +\definebtxcommand\MP {METAPOST} +\definebtxcommand\sltt{\tt} +\definebtxcommand\<#1>{\type{#1}} +\stopTEX + +\definebtxcommand\MP {METAPOST} % to be used silently below + +Custom commands created using \Cindex {definebtxcommand} have the advantage of +using a separate name space thus allowing \Index {isolation} from other \CONTEXT\ +commands. (The \Index {isolation} of \Cindex {btxcommand} allows the \Tindex +{.bib} files to safely contain \TEX\ and \LATEX\ idiosyncrasies that might +conflict with proper \CONTEXT\ syntax.) Unknown commands do not stall processing, +but their names are then typeset in a mono|-|spaced font so they probably stand +out for proofreading. You can access the commands using \index +{btxcommand}\TEXcode {\btxcommand{...}} (or \Cindex {btxcmd}), as in: + +\startbuffer +commands like \btxcommand{MySpecialCommand} are handled in an indirect way +\stopbuffer + +\cindex{btxcommand} + +\typeTEXbuffer + +As this is an undefined command we get: \quotation {\inlinebuffer}. + +Often, these embedded \TEX\ commands are present in \Tindex{.bib} files in order +to trick \BIBTEX\ into certain behavior. Since this will generally not be +necessary here, we strongly encourage users to clean|-|up such unnecessary +extras. Indeed, the idea is to keep the data clean, using styles and parameter +settings instead to handle rendering issues. Indeed, we don't see it as challenge +nor as a duty to support all kinds of messy definitions. Of course, we try to be +somewhat tolerant, but you will be sure to get better results if you use nicely +setup, consistent databases. + +Finally, the \BIBTEX\ entry \tindex {@string}\BTXcode {@String{}} is preprocessed +as expected. + +\tindex{@string} + +\startTEX +@String{j-TUGboat = "TUGboat"} +\stopTEX + +\startaside +Notice that \Tindex {tugboat.bib} also contains: \tindex {@preamble} +\startBTX +@Preamble{"\input tugboat.def"} +@Preamble{"\input path.sty"} +\stopBTX +These are silently ignored as many such commands are most likely not to be +compatible with \CONTEXT. Indeed, the examples shown here are not! +\stopaside + +\stopsection + +\startsection[title=\MKII\ definitions] + +In the old \MKII\ setup we have two kinds of entries: the ones that come from the +\BIBTEX\ run and additional user|-|supplied ones. We no longer rely on \BIBTEX\ +output but we do still support the user supplied definitions. These were in fact +prepared in a way that suits the processing of the \BIBTEX\ generated entries; +The next variant reflects the \CONTEXT\ recoding of the old \BIBTEX\ output. For +this reason, some users refer to this as \Tindex {.bbl} format. + +\cindex{startpublication} +\cindex{stoppublication} + +\startTEX +\startpublication[k=Hagen:Second,t=article,a={Hans Hagen},y=2013,s=HH01] + \artauthor[] {Hans}[H.]{}{Hagen} + \arttitle {Who knows more?} + \journal {MyJournal} + \pubyear {2013} + \month {8} + \volume {1} + \issue {3} + \issn {1234-5678} + \pages {123--126} +\stoppublication +\stopTEX + +The split \TEXcode {\artauthor} fields will be collapsed into a single \TEXcode +{author} field as we handle the splitting later when it gets parsed in \LUA. The +\TEXcode {\artauthor} syntax is only kept around for backward compatibility with +the previous use of \BIBTEX. + +In the new setup we support these variants: + +\cindex{startpublication} +\cindex{stoppublication} + +\startTEX +\startpublication[k=Hagen:Third,t=article] + \author{Hans Hagen} + \title {Who knows who?} + ... +\stoppublication +\stopTEX + +as well as + +\cindex{startpublication} +\cindex{stoppublication} + +\startTEX +\startpublication[tag=Hagen:Third,category=article] + \author{Hans Hagen} + \title {Who knows who?} + ... +\stoppublication +\stopTEX + +and + +\cindex{startpublication} +\cindex{stoppublication} + +\startTEX +\startpublication + \tag {Hagen:Third} + \category{article} + \author {Hans Hagen} + \title {Who knows who?} + ... +\stoppublication +\stopTEX + +The use of this format will be illustrated later a means to export the database +which may be of great use in converting collections of \MKII\ bibliography files. + +\showsetup[startpublication] + +\stopsection + +\startsection[title=\LUA\ tables] + +Because internally the entries are \index [LUA table] {\LUA\ table}\LUA\ tables, +we also support the loading of \LUA\ based definitions: + +\startLUA +return { + ["Hagen:First"] = { + author = "Hans Hagen", + category = "article", + issn = "1234-5678", + issue = "3", + journal = "MyJournal", + month = "8", + pages = "123--126", + tag = "Hagen:First", + title = "Who knows nothing?", + volume = "1", + year = "2013", + }, +} +\stopLUA + +Notice that the \Index {tag} is redundantly specified; it is \quote {pushed} into +the table so that one can access it without having to know the \Index {tag} of the +original table. + +\stopsection + +\startsection[title=\XML] + +The following \index [XML] {\XML}\XML\ input is rather close in structure, and is +also accepted as input. + +\startXML +<?xml version="2.0" standalone="yes" ?> +<bibtex> + <entry tag="Hagen:First" category="article"> + <field name="author">Hans Hagen</field> + <field name="category">article</field> + <field name="issn">1234-5678</field> + <field name="issue">3</field> + <field name="journal">MyJournal</field> + <field name="month">8</field> + <field name="pages">123--126</field> + <field name="tag">Hagen:First</field> + <field name="title">Who knows nothing?</field> + <field name="volume">1</field> + <field name="year">2013</field> + </entry> +</bibtex> +\stopXML + +We shall focus on the use of \BIBTEX\ \Tindex {.bib} files as the input data +format of reference. Keep in mind, however, that the \index [LUA table] {\LUA\ +table}\LUA\ table format and the \index [XML] {\XML}\XML\ format might prove to +be more flexible for future expansion of functionality. + +\stopsection + +\startsection[title=Other formats] + +Various other bibliographic data file formats are in common use, such as: + +\starttabulate [|Tl|p|] +\NC savedrecs.txt \NC Institute of Scientific Information (ISI) tagged format + (e.g. Thomson Reuters™ Web of Science™), \NC \NR +\NC filename.enw \NC Thomson Reuters™ Endnote™ export format + (there is also an Endnote \type {.xml} export), \NC \NR +\NC filename.ris \NC Research Information Systems, Incorporated, now + Thomson Reuters™ Reference Manager™, and \NC \NR +\NC pubmed_result.txt \NC The National Library of Medicine® (NLM®) + MEDLINE®|/|PubMed® data format \NC \NR +\stoptabulate + +just to name a few (amongst many more). Filters can be easily written in \LUA\ to +read these and other bibliography data formats, although no such filters are +provided. This is because the user has a choice of a certain number of +bibliography database management programs that can easily convert from these to +the \BIBTEX\ format. (Notable, open source examples are \index{jabref} \goto +{jabref} [url(http://jabref.sourceforge.net)] and \index{zotero} \goto {zotero} +[url(http://www.zotero.org)].) Indeed, it is not the vocation of the present +\CONTEXT\ bibliography subsystem to fully manage the bibliography data sources, +only to be able to use such data in the production of documents. + +\startaside +\emphasis {A note on database management programs:} these are very valuable tools +for the manipulation of bibliography database information, which is why the +\BIBTEX\ format has so much importance for us here. However, one must be aware +that these programs are not standards and many of them may introduce invalid +extensions that might not even be handled correctly by \BIBTEX\ itself. +\stopaside + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-datasets.tex b/doc/context/sources/general/manuals/publications/publications-datasets.tex new file mode 100644 index 000000000..c9b5698cb --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-datasets.tex @@ -0,0 +1,333 @@ +\environment publications-style + +\startcomponent publications-datasets + +\startchapter[title=Datasets] + +Normally in a document you will use only one bibliographic database, whether or +not its source is distributed over multiple files. Nevertheless, we support +multiple database formats as well which is why we talk of datasets instead. The +use of multiple datasets allows the isolation of different bibliographies (a +single bibliography can nevertheless be rendered by structure element: section, +chapter, part, etc. as we shall see later). A good example of the use of multiple +datasets would be for a proper bibliography itself in addition to a reference +catalog (of equipment, suppliers, software, patents, legal jurisprudence, music, +\unknown). Indeed, datasets can be used to hold both bibliographic and +non|-|bibliographic information. + +A dataset is initiated with the \Cindex {definebtxdataset} command. + +\cindex{definebtxdataset} + +\startTEX +\definebtxdataset[default] +\stopTEX + +\startaside +A default database, \TEXcode {default}, is predefined, yet we recommend defining +it explicitly because in the future we may provide more options. +\stopaside + +Like other commands in \CONTEXT, the dataset options can be setup using the +command \Cindex {setupbtxdataset}. + +\cindex{definebtxdataset} +\showsetup[definebtxdataset] + +\cindex{setupbtxdataset} +\showsetup[setupbtxdataset] + +A dataset is loaded from some source through the use of the +\Cindex {usebtxdataset} command. + +Here are some examples: + +\cindex{usebtxdataset} +\tindex{.bib} +\tindex{.xml} +\tindex{.lua} +\tindex{.bbl} + +\startTEX +\usebtxdataset[tugboat][tugboat.bib] +\usebtxdataset[default][mtx-bibtex-output.xml] +\usebtxdataset[default][test-001-btx-standard.lua] +\usebtxdataset[default][mkii-publications.bbl] +\usebtxdataset[default][named.buffer] +\stopTEX + +\cindex{usebtxdataset} +\showsetup[usebtxdataset] + +The four suffixes illustrated in the example above are understood by the loader. +Here the dataset (other than the first) has the name \TEXcode {default} and the +four database files are merged. The last example shows that a \TEXcode {named} +\Index {buffer} can also be employed to add dataset entries (in \BIBTEX\ format). +This may be useful for small additions or examples, but it is generally a better +idea (for convenience of management of data) to place them in files separate from +the document source code. + +Definitions in the document source (coded in \TEX\ speak) are also added, and +they are saved for successive runs. This means that if you load and define +entries, they will be known at a next run beforehand, so that references to them +are independent of where in the document source loading and definitions take +place. This is convenient to eventually break|-|up the dataset loading calls to +relevant sections of the document structure. + +In this document we use some example databases, so let's load one of them now: +\startfootnote This code snippet demonstrates that \TEXcode {\usebtxdataset} will +implicitly declare an undefined dataset name, although this practice is to be +discouraged. Similarly, omitting to specify the dataset name \TEXcode {[default]} +in the examples given earlier would fall|-|back correctly, but this, too, is to +be discouraged as being potentially error|-|prone. \stopfootnote + +\startbuffer +\usebtxdataset[example][mkiv-publications.bib] +\stopbuffer + +\cindex{definebtxdataset} +\cindex{usebtxdataset} + +\typeTEXbuffer + +\getbuffer + +The beginning of the file \type {mkiv-publications.bib} is shown below in \in +{table} [tab:mkiv-publications.bib]. This bibliography database test file +contains one entry of each standard type or category, with the \Index {tag} set +to the entry type name. This entry shown here illustrates many features that will +be explained elsewhere in the text. + +\startplacetable + [reference=tab:mkiv-publications.bib, + title={mkiv-publications.bib\\ + This test file was constructed to illustrate various features of the + \BIBTEX\ format and contains some fields that might at first glance + appear somewhat curious.}]. + \typeBTXfile + [range={@Comment{Start example},@Comment{Stop example}}] + {mkiv-publications.bib} +\stopplacetable + +\startsection[title=Dataset coverage] + +You can load much more data than you actually need. Usually only those entries +that are referred to explicitly will be shown in lists, and commands used to +select these dataset entries will described in \in {chapter} [ch:cite]. + +A single bibliography list can span groups of datasets; also multiple datasets +can loaded from the same source, for example, one per chapter, in order to +achieve a complete \Index {isolation} of bibliographies with respect to numbering +and references. + +As this concept is not obvious but can be quite useful, we will repeat this last +point: multiple datasets can be loaded using the same source file, i.e.\ +containing the same data, to be used in parallel, independently. There is little +penalty in keeping even very large datasets as multiple copies in memory. + +The current active dataset to be used by default can be set with + +\startbuffer +\setupbtx[dataset=example] +\stopbuffer + +\cindex{setupbtx} + +\typeTEXbuffer + +\getbuffer + +However, most publication|-|related commands accept optional arguments that +denote the dataset and references to entries can always be prefixed with a +dataset identifier. More about that later. + +\showsetup[setupbtx] + +\stopsection + +\startsection [title=Specification] + +The content of a dataset can really be anything: entries of type (or categories) +of all sorts, each containing arbitrary fields. The use to be made of this data +can vary greatly since the system is not limited to the production of +bibliography lists, in particular. The intended use is reflected through a set of +specifications, specific to each bibliography (or non|-|bibliography) style. +These specifications affect the interpretation of dataset categories and fields +as well as their rendering. They will also affect the rendering of citations or +the reference or invocation of individual data entries. + +The \TEXcode {default} bibliography specification is very simple: only the +categories \TEXcode {book} and \TEXcode {article} are explicitly defined. These +were shown along with their default rendering in the quick|-|start example on \at +{page} [ch:quick]. We purposely limited this \TEXcode {default} specification as +a minimal example for a bibliography. + +The notion of categories and the fields that they might contain and their +interpretation depend on a particular specification, although the dataset +\emphasis {content} is independent of all eventual rendering specifications that +may be applied. + +An alternative set of specifications can be selected using, for example + +\startbuffer +\usebtxdefinitions[apa] +\stopbuffer + +\cindex{usebtxdefinitions} +\index{style+APA} +\seeindex{specification}{style} + +\typeTEXbuffer + +\getbuffer + +Alternately, the set of specifications can be loaded and (later) activated using + +\cindex{loadbtxdefinitionfile} +\cindex{setupbtx} +\index{style+APA} + +\startTEX +\loadbtxdefinitionfile[apa] +... +\setupbtx[specification=apa] +\stopTEX + +but it is safer to use the \TEXcode {\use} rather than \TEXcode {\load} form, in +particular with specifications that may themselves have several variants. Also, +it is way too easy to later forget to set the \TEXcode {specification} parameter +and then wonder why the loaded specification was not applied. + +\startaside +We wish to clarify that each specification defines the categories of entries and +the interpretation or use of the fields that they contain, but does not alter the +data itself, only how this data is used. It also defines \emphasis {setups} that +control the rendering of lists as well as citations (to be described below). +Additionally, it creates a namespace with settings for particular \emphasis +{parameters} controlling the formatting of names, for example, punctuation as +well as other stylistic features. The user can tune or overload these settings as +needed. +\stopaside + +A specification need not be activated before loading a dataset; indeed the +contents of a dataset are stored independent of the specification, and multiple +specifications can be applied to the same dataset (although this will not usually +be the case). Furthermore, multiple specification files can be loaded +simultaneously as they reside in separate namespaces, but only one specification +can be selected at a time. We introduce these commands here in the context of +datasets as the labeling of categories and of field use can change depending on +the specification. Indeed, some specifications might ignore certain fields +present in the dataset that may be used with other specifications. The details of +how this is programmed will be explained in \in {Chapter} [ch:custom]. + +So a specification is both a definition of how a dataset is to be interpreted as +well as stylistic tuning of how it is to be rendered. + +\cindex {loadbtxdefinitionfile} +\showsetup[loadbtxdefinitionfile] + +\cindex {usebtxdefinitions} +\showsetup[usebtxdefinitions] + +\stopsection + +\startsection [title=Dataset diagnostics] + +You can ask for an overview of entries present in a dataset with: + +\startbuffer +\showbtxdatasetfields[example] +\stopbuffer + +\cindex{showbtxdatasetfields} + +\typeTEXbuffer + +The listing that this produces is shown in \in {Appendix} [ch:datasetfields]. + +\cindex {showbtxdatasetfields} +\showsetup[showbtxdatasetfields] +\showsetup[showbtxdatasetfields:argument] + +Sometimes you might want to check a database, listing all of its entries in +detail. This can be particularly useful when in doubt concerning the correctness +or the completeness of the data source, remembering that invalid entries and some +syntax errors are simply skipped over. One way of examining the loaded dataset in +detail is the following: + +\startbuffer +\showbtxdatasetcompleteness[example] +\stopbuffer + +\cindex{showbtxdatasetcompleteness} + +\typeTEXbuffer + +The diagnostic listing (which can be rather long) is shown in \in {Appendix} +[ch:datasetcompleteness]. + +\cindex {showbtxdatasetcompleteness} +\showsetup[showbtxdatasetcompleteness] +\showsetup[showbtxdatasetcompleteness:argument] + +The dataset contains many entries and each entry is assigned to a \Index +{category}. It must be stressed, so we repeat ourselves here, that these \quote +{categories} can be of any sort whatsoever, the meaning of which resides in the +rendering style that is chosen. The entries contain fields, and these too can be +of any sort; their use also depends on the rendering style and the \Index +{category} in which they belong. \BibTeX\ has conventionally defined a number of +standard categories, each making use of a number of fields considered either +\index {field+required}required, \index {field+optional}optional or \index +{field+ignored}ignored. However, different traditional \BIBTEX\ rendering styles +can make inconsistant use of these standard categories and fields. To make +matters worse, different \Tindex {.bib} database handling programs might use (and +impose) differing \quote {standards} as well, as mentioned above. \startfootnote +For example, \Tindex {jabref}, in addition to discarding all comments contained +in the database file, will convert all unrecognized, preciously named categories +to \tindex {@other}\BTXcode {@Other}! Of course, \Tindex {jabref} is flexible +enough to be configured with new categories and additional fields, so users of +\Tindex {jabref} with \CONTEXT\ will probably want to use an extended, custom +configuration. \stopfootnote This situation arises from the complexity of +handling bibliographic data of all sorts. + +You can see all (currently known) \index {category}categories and \index +{field}fields with: + +\cindex{showbtxfields} + +\startTEX +\showbtxfields[rotation=...] +\stopTEX + +The result is shown \in {table} [tab:fields], below. + +\startplacetable + [reference=tab:fields, + list={\TEXcode {\showbtxfields[rotation=90]}}, + title={\cindex {showbtxfields}\TEXcode {\showbtxfields[rotation=90]} The entry + \Index {category} and \Index {field} names (and how they are used) are + defined by both the rendering style as well as by the contents of the + dataset. \index {field+required}\quote {Required} fields are indicated + in green. All unmarked fields are normally \index + {field+ignored}ignored in the rendering.}] + \small + \showbtxfields[rotation=90] +\stopplacetable + +\cindex {showbtxfields} +\showsetup[showbtxfields] +\showsetup[showbtxfields:argument] + +Note that other, possibly non|-|bibliographic use of the present dataset system +might define entirely different categories and field types, possibly having +nothing at all to do with the names shown here. An example of such use is given +in \in {chapter} [ch:duane]. + +Just as a database can be much larger than needed for a document, the same is +true for the fields that make up an entry; not all entry fields will be +necessarily used. This idea will be developed in the next section describing the +rendering of bibliography lists. + +\stopsection + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-exporting.tex b/doc/context/sources/general/manuals/publications/publications-exporting.tex new file mode 100644 index 000000000..b459ce118 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-exporting.tex @@ -0,0 +1,33 @@ +\environment publications-style + +\startcomponent publications-exporting + +\startchapter[title=Exporting datasets] + +A dataset can be much more complete than necessary. Furthermore, it may be +desirable to isolate bibliography data by chapter, for example, or by any other +structural element such as part. To achieve this, it is possible to export the +entries of a dataset following certain criteria. + +\cindex{savebtxdataset} + +Take as an example, the bibliography of the present manual that was entered in +the source as buffers for convenience. The entries can be saved to a legitimate +\BIBTEX\ format file using: + +\startTEX +\savebtxdataset + [default] + [mkvi-publications.bib] + [alternative=bib, + criterium=all] +\stopTEX + +This can also be used to convert older bibliography source files (for example, +kept in the \tindex {.bbl}\MKII\ format) into the \tindex {.bib}\type {bib}, +\tindex {.lua}\type {lua} or even \tindex {.xml}\type {xml} format that could be +more convenient for future manipulation. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-extensions.tex b/doc/context/sources/general/manuals/publications/publications-extensions.tex new file mode 100644 index 000000000..262d5eb3c --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-extensions.tex @@ -0,0 +1,119 @@ +\environment publications-style + +\startcomponent publications-extensions + +\startchapter[title=Extensions] + +As \TEX\ and \LUA\ are both open and accessible in \CONTEXT\ it is possible to +extend the functionality of the bibliography related code. For instance, you +could add extra loaders, sketched as follows: + +\startTEX +\startluacode +function publications.loaders.myformat(dataset,filename) + local t = { } + -- Load data from 'filename' and convert it to a Lua table 't' with + -- the key as hash entry and fields conforming the luadata table + -- format. + loaders.lua(dataset,t) +end +\stopluacode +\stopTEX + +This would then permit the loading a database (into a dataset) with the command: + +\cindex{usebtxdataset} + +\startTEX +\usebtxdataset[default][myfile.myformat] +\stopTEX + +The \type {myformat} suffix is recognized automatically. If you want to use another +suffix, you can do this: + +\cindex{usebtxdataset} + +\startTEX +\usebtxdataset[default][myformat::myfile.txt] +\stopTEX + +%% NO SETUP BTX:APA:LEFTTEXT SO THE FOLLOWING DOES NOT WORK: +%% +%% If you want to add information to an entry at runtime you can pass so called user +%% variables with the \type {\cite} command. The following example demonstrates +%% this. First we define a dataset: +%% +%% \startbuffer +%% \startbuffer [knuth] +%% @Book{knuth-texbook, +%% title = {The TeXbook}, +%% author = {Knuth, Donald Ervin}, +%% isbn = {0-201-13447-0}, +%% series = {Computers {\&} Typesetting}, +%% volume = {A}, +%% year = {1986}, +%% publisher = {Addison Wesley}, +%% address = {Reading, MA}, +%% } +%% \stopbuffer +%% +%% \definebtxdataset[knuth] +%% \usebtxdataset [knuth] [knuth.buffer] +%% \definebtxrendering[knuth][dataset=knuth] +%% \stopbuffer +%% +%% \typeTEXbuffer +%% \getbuffer +%% +%% \startbuffer[setup] +%% \startsetups btx:apa:lefttext +%% \currentbtxlefttext +%% \btxspace +%% \btxdoifelseuservariable {notabene} { +%% {\bs \currentbtxuservariable{notabene}} +%% } { +%% % nothing +%% } +%% \btxspace +%% \stopsetups +%% \stopbuffer +%% +%% \getbuffer[setup] +%% +%% \startbuffer +%% We all know the \TeX book by Don Knuth \citation [reference=knuth::knuth-texbook, +%% lefttext={\bf >}] [notabene=Well known to \TEX\ users:]. +%% \stopbuffer +%% +%% We use this example where we use \type {\citation} instead of \type {\cite} because +%% it is more tolerant with spaces. Because we pass user variables as second argument +%% the first argument also has to be a key|/|value set. +%% +%% \typeTEXbuffer +%% +%% \getbuffer +%% +%% The list is typeset using: +%% +%% \startbuffer +%% \placelistofpublications [knuth] [criterium=all] +%% \stopbuffer +%% +%% \typeTEXbuffer +%% +%% and looks like this: +%% +%% \getbuffer +%% +%% The injection of the user variables is up to you. Here we hooked it into an +%% existing setup that we overload: +%% +%% \typeTEXbuffer [setup] +%% +%% The \type {lefttext} and \type {righttext} variables are also kept with the +%% entry but these are checked for automatically. In this case it means that +%% when no \type {lefttext} is specified, the \type {notabene} doesn't show up. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-fields.tex b/doc/context/sources/general/manuals/publications/publications-fields.tex new file mode 100644 index 000000000..adbdb373b --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-fields.tex @@ -0,0 +1,38 @@ +\environment publications-style + +\startcomponent publications-fields + +\startchapter + [title={Dataset fields}, + reference=ch:datasetfields] + +\setupbtx + [specification=apa] + +\usebtxdataset + [example] + [mkiv-publications.bib] + +\startbuffer +\showbtxdatasetfields[example] +\stopbuffer + +\typeTEXbuffer + +\cindex {showbtxdatasetfields}The field names for each entry \Index {category} +are colored according to their status with respect to the bibliography rendering +style. The \index {field+required}\quote {required} field names are colored in +green, where required means that if this field is missing, one is probably not +using the correct entry type or category. Some fields are \index +{field+optional}\quote {optional} (and some \index {field+required}\quote +{required} fields can become conditionally optional, see below). Fields that +normally would be \index {field+ignored}ignored (defined as neither required, nor +optional) are colored in dark yellow. Some fields are treated as \index +{field+special}\quote {special}, that is are used internally, not necessarily +directly rendered, and are colored here in blue. + +\getbuffer + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-introduction.tex b/doc/context/sources/general/manuals/publications/publications-introduction.tex new file mode 100644 index 000000000..53abf5d83 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-introduction.tex @@ -0,0 +1,109 @@ +\environment publications-style + +\startcomponent publications-introduction + +\startchapter[title=Introduction] + +\startsubject[title=How Hans got involved] + +This manual is dedicated to Taco \Name{Hoekwater}{T.} who in a previous century +implemented the first \BIBTEX\ module and saw it morph into a \TEX||\LUA\ hybrid +in this century. The fact that there was support for bibliographies made it +possible for users to use \CONTEXT\ in an academic environment, dominated by +bibliographic databases encoded in the \BIBTEX\ format. + +This manual describes how \MKIV\ now handles bibliographies. Support in \CONTEXT\ +started in \MKII\ for \BIBTEX, as mentioned above, using a module written by Taco +\Name {Hoekwater} {T.}. Later his code was adapted to \MKIV, but because users +demanded more, I decided that reimplementing made more sense than patching. In +particular, through the use of \LUA, the \BIBTEX\ data files can be easily +directly parsed, thus liberating \CONTEXT\ from the dependency on an external +\BIBTEX\ executable. The \Index{CritEd project} (by Thomas \Name {Schmitz} {T.}, +Alan \Name {Braslau} {A.}, Luigi \Name {Scarso} {L.} and \name {Hagen} +{H.}myself) was a good reason to undertake this rewrite. As part that project +users were invited to come up with ideas about extensions. Not all of them are +(yet) honored, but the rewrite makes more functionality possible. + +The subsystem described here is one of the most complex and messy of all +\CONTEXT\ subsystems. This has to do with the fact that it combines (multiple) +lists and (multiple) forward and backward references, all kind of rendering of +the citation as well as the entry in the list, rather complex interactivity, +multiple databases, datasets and renderings and of course combinations of this. +The implementation uses a mix of \TEX\ and \LUA\ code with so called setups as +rendering specifications. At the cost of complexity (and some runtime penalty) +this provides a lot of freedom and flexibility. + +% \startlines +% Hans \Name {Hagen} {H.} +% PRAGMA ADE +% Hasselt NL +% \stoplines + +\stopsubject + +\startsubject[title=How Alan got involved] + +Bibliographies and citations are of utmost importance in any scholarly work. +Nevertheless, the production of bibliography lists and the insertion of +citations, just like the production of an index, is a task that is often +postponed to a later stage in the writing of an article, a book, or a manual. +Perhaps this is because it can be more important to create than to refer, but +maybe the necessary tools are found to be insufficient or unnatural. + +A computerized typesetting system should help an author produce a text, not +impose any preset format or unnecessary constraint. In a referenced work, a +bibliography system should be flexible enough to adapt to very different styles +and practices. Creating such a system is quite a challenge. + +\CONTEXT\ \MKII\ implemented a system that was based on a use of \BIBTEX, an +external program that built upon basic bibliographic macros introduced in \LATEX. +\CONTEXT\ \MKIV\ moved away from this dependency, opening up many possibilities +for new functionality and, we hoped, providing more natural and flexible tools +for authors. For my own use, the most important of which is a very powerful +search and match mechanism that has been made possible though the use of \LUA. + +I had started by asking simple questions on details of the workings of this new +system and making \quotation{wouldn't it be nice to} requests for functionality +that I knew was somehow buried in the inner workings of \CONTEXT. As a result of +these inquiries, I got drawn into the project to make this new system a reality. + +% \startlines +% Alan \Name{Braslau}{A.} +% Paris, France +% \stoplines + +\stopsubject + +\startsubject[title=How you can be involved] + +Bibliography management is indeed one of the most complex subsystems in \CONTEXT, +and many, many design decisions had to be made during its development. +Experimental features were added, some of which were later abandoned as being +inappropriate or else superseded by some better mechanism. The effort (and time) +that we spent in reimplementing the treatment of bibliographies was much greater +than any of us had anticipated when we undertook this project. Hopefully, now the +system is stable enough to be more widely used and this manual is an attempt to +make it accessible to all users. + +There are \CONTEXT\ users who will just use whatever the bibliograpy modules +provide by default. For many, the \APA\ style is good enough; others may have +specific needs. This manual should provide insight on how to adapt the system to +new styles. But sometimes users will ask questions on the mailing list that are +not answered here. Feel free to come up with additional examples that can be +added to the test suite, or when we consider them to be of general use, to this +manual. + +\stopsubject + +\startsubject[title=Hyperlinks] + +Please note \startfootnote Footnotes are placed at the end of each chapter. +\stopfootnote that this document contains hyperlinks that are not highlighted for +aesthetic reasons. In addition to standard interaction (table of contents, index, +and cross|-|references, some external web sources are selectable. + +\stopsubject + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-journals.tex b/doc/context/sources/general/manuals/publications/publications-journals.tex new file mode 100644 index 000000000..0dd8a872f --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-journals.tex @@ -0,0 +1,88 @@ +% \endinput + +\environment publications-style + +\startcomponent publications-journals + +\startchapter[title=Journals] + +An experimental feature is the ability to load a list of mapping from complete +journal names to abbreviated forms. + +\startbuffer +\btxloadjournallist[journals.txt] % the jabref list + +\btxexpandedjournal {Z. Ökol. Nat.schutz} or +\btxabbreviatedjournal{Z. Ökol. Nat.schutz} or +\btxabbreviatedjournal{Z. Ökol. Nat. schutz} +\stopbuffer + +\typeTEXbuffer \getbuffer + +In this case the text file looks like: + +\starttyping +Zeitschrift für Ökologie und Naturschutz = Z. Ökol. Nat..schutz +.... +\stoptyping + +Instead you can have a \LUA\ file that looks like: + +\startLUA +return { + ["Zeitschrift für Ökologie und Naturschutz"] = "Z. Ökol. Nat.schutz", + ... +} +\stopLUA + +or + +\startLUA +return { + { "Zeitschrift für Ökologie und Naturschutz", "Z. Ökol. Nat.schutz" }, + ... +} +\stopLUA + +A file can be saved with: + +\startTEX +\btxsavejournallist[journals.lua] +\stopTEX + +and then loaded again in a second run. For small lists it makes not much sense +to cache the lists but if you have tens thousands of journals it can be +considered. Normally loading is can be neglected compared to the run. Anyhow, +such a list looks like this: + +\startLUA +return { + ["abbreviations"]={ + ["zeitschriftfürökologieundnaturschutz"] = "Z. Ökol. Nat.schutz", + }, + ["expansions"]={ + ["zökolnatschutz"] = "Zeitschrift für Ökologie und Naturschutz", + }, +} +\stopLUA + +In the future \type {mtx-bibtex} might be able to generate such lists (once we know +what users come up with). + +You can add additional entries with: + +\startTEX +\btxaddjournal + [Zeitschrift für Ökologie und Naturschutz] + [Z. Ökol. Nat.schutz] +\stopTEX + +As usual with such mechanisms, internally spaces, punctuation and case are +ignored with a lookup. + +There are also two manipulators for journals: \type {expandedjournal} and +\type {abbreviatedjournal}. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-lua.tex b/doc/context/sources/general/manuals/publications/publications-lua.tex new file mode 100644 index 000000000..4bbc73a2f --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-lua.tex @@ -0,0 +1,224 @@ +\environment publications-style + +\startcomponent publications-lua + +\startchapter[title=The \LUA\ view] + +The following is reserved for \LUA\ programmers. + +Because we manage data at the \LUA\ end it is tempting to access it there for +other purposes. This is fine as long as you keep in mind that aspects of the +implementation may change over time, although this is unlikely once the modules +become stable. + +The entries are collected in datasets and each set has a unique name. In this +document we have the set named \type {example}. A dataset table has several +fields, and probably the one of most interest is the \type {luadata} field. Each +entry in this table describes a publication. Take, for example \type +{publications.datasets.example.luadata["article"]}: + +\startluacode + context.tocontext(publications.datasets.example.luadata["article"]) +\stopluacode + +There is a companion entry in the parallel \type {details} table,\\ +\type {publications.datasets.example.details["article"]}: + +\startluacode + context.tocontext(publications.datasets.example.details["article"]) +\stopluacode + +tracking further information derived from the publication entry and its use. + +You can loop over the entries using regular \LUA\ code combined with \MKIV\ +helpers: + +\startbuffer +local dataset = publications.datasets.example + +context.starttabulate { "|l|l|l|" } +context.NC() context("tag") +context.NC() context("short") +context.NC() context("title") +context.NC() context.NR() +context.HL() +for tag, entry in table.sortedhash(dataset.luadata) do + local detail = dataset.details[tag] or { } + context.NC() context.type(tag) + context.NC() context(detail.shorthash) + context.NC() context(entry.title) + context.NC() context.NR() +end +context.stoptabulate() +\stopbuffer + +\typeLUAbuffer + +This results in: + +\ctxluabuffer + +Notice that the years in this example dataset given as \type {YYYY} are +interpreted as if they were \index {9999}\type {9999}. + +You can manipulate a dataset after loading. Of course this assumes that you know +what kind of content you have and what you need for rendering. As example we load +a small dataset. + +\startbuffer +\definebtxdataset[drumming] +\usebtxdataset[drumming][mkiv-publications.lua] +\stopbuffer + +\cindex{definebtxdataset} +\cindex{usebtxdataset} + +\typeTEXbuffer + +\getbuffer + +Because we're going to do some \LUA, we could have loaded this dataset using: + +\startTEX +\startluacode +publications.load("drumming","mkiv-publications.lua","lua") +\stopluacode +\stopTEX + +The dataset has three entries:% +\startfootnote +Gavin Harrison is in my (Hans) opinion one of the most creative, diverse and +interesting drummers of our time. It's also fascinating to watch him play and a +welcome distraction from writing code and manuals. +\stopfootnote + +\typeLUAfile{mkiv-publications.lua} + +As you can see, we can have a subtitle. As an exercise, we will combine the +title and subtitle into one: + +\startbuffer +\startluacode +local luadata = publications.datasets.drumming.luadata + +for tag, entry in next, luadata do + if entry.subtitle then + if entry.title then + entry.title = entry.title .. ", " .. entry.subtitle + else + entry.title = entry.subtitle + end + entry.subtitle = nil + logs.report("btx", + "combining title and subtitle of entry tagged %a into %a", + tag,entry.title) + end +end +\stopluacode +\stopbuffer + +\typeTEXbuffer \getbuffer + +As a hash comes in a different order each run (something that demands a lot of +care in multi|-|pass workflows that save data in between), so it is probably +better to use this instead: + +\startTEX +\startluacode +local ordered = publications.datasets.drumming.ordered + +for i=1,#ordered do + local entry = ordered[i] + if entry.subtitle then + if entry.title then + entry.title = entry.title .. ", " .. entry.subtitle + else + entry.title = entry.subtitle + end + entry.subtitle = nil + logs.report("btx", + "combining title and subtitle of entry tagged %a into %a", + entry.tag,entry.title) + end +end +\stopluacode +\stopTEX + +This loops processes in the order of definition. Alternately, one can sort by +\Index{tag}: + +\startTEX +\startluacode +local luadata = publications.datasets.drumming.luadata + +for tag, entry in table.sortedhash(luadata) do + if entry.subtitle then + if entry.title then + entry.title = entry.title .. ", " .. entry.subtitle + else + entry.title = entry.subtitle + end + entry.subtitle = nil + logs.report("btx", + "combining title and subtitle of entry tagged %a into %a", + entry.tag,entry.title) + end +end +\stopluacode +\stopTEX + +The original data is stored in a \LUA\ table, hashed by tag. Starting with \LUA\ 5.2 +each run of \LUA\ gets a different ordering of such a hash. In older versions, when you +looped over a hash, the order was undefined, but the same as long as you used the same +binary. This had the advantage that successive runs, something we often have in document +processing gave consistent results. In today's \LUA\ we need to do much more sorting of +hashes before we loop, especially when we save multi||pass data. It is for this reason +that the \XML\ tree is sorted by hash key by default. That way lookups (especially +the first of a set) give consistent outcomes. + +We can now simply typeset the entries with: + +\cindex{definebtxrendering} +\cindex{placebtxrendering} + +\startbuffer +\definebtxrendering[drumming][dataset=drumming,method=dataset] +\placebtxrendering[drumming] +\stopbuffer + +\typeTEXbuffer \getbuffer + +Because we just want to show the entries, and have no citations that force them +to be shown, we have to set the \type {method} to \type {dataset}. + +Of course, none of these manipulations in \LUA\ are really necessary, as the +rendering could be setup as: + +\cindex {btxfetch} +\cindex {btxdoif} +\cindex {btxcomma} +\cindex {starttexdefinition} +\cindex {stoptexdefinition} + +\startTEX +\starttexdefinition btx:default:title + \btxfetch{author} + \btxdoif{subtitle} { + \btxcomma + \btxfetch{subtitle} + } +\stoptexdefinition +\stopTEX + +which is indeed the case in many of the styles (the \type {default} style uses +\Cindex {btxcolon}). \startfootnote The specifications could be modified to use a +parameter \type {inbetween={, }} for titles:subtitles that the user can easily +setup as needed. But as such style questions are, in general, well defined in the +specifications, this was not deemed necessary. \stopfootnote + +It is always a question of how much should be done in \LUA\ and how much should +be done in \TEX. In the end, it is often a question of taste. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-otheruse.tex b/doc/context/sources/general/manuals/publications/publications-otheruse.tex new file mode 100644 index 000000000..8f42f65eb --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-otheruse.tex @@ -0,0 +1,168 @@ +\environment publications-style + +\startcomponent publications-otheruse + +\startchapter + [reference=ch:duane, + title=Other use of datasets] + +Because a bibliography is just a kind of database, you can use the publications +mechanism for other purposes as well. During the re|-|implementation \name +{Miklavec}{M.}Mojca came up with the following definitions: + +\startbuffer +\startbuffer[duane] +@IMAGE {tug2013, + title = "TUG 2013", + url = "http://tug.org/tug2013/", + url_image = "http://tug.org/tug2013/tug2013-color-300.jpg", + url_thumb = "http://tug.org/tug2013/t2013-thumb.jpg", + description = "Official drawing of the TUG 2013 conference", + author = "Duane Bibby", + year = 2013, + copyright = "TUG", +} + +@IMAGE {tug2014, + title = "TUG 2014", + url = "http://tug.org/tug2014/", + url_image = "http://tug.org/art/tug2014-color.jpg", + url_thumb = "http://tug.org/tug2014/t2014-thumb.jpg", + description = "Official drawing of the TUG 2014 conference", + author = "Duane Bibby", + year = 2014, + copyright = "TUG", +} +\stopbuffer +\stopbuffer + +\typeBTXbuffer \name{Bibby}{D.}\getbuffer + +For documentation purposes we can have a definition in a buffer so that we can +show it verbatim but also load it. The following code defines a dataset, loads +the buffer and sets up a rendering. + +\startbuffer +\definebtxdataset + [duane] + +\usebtxdataset + [duane] + [duane.buffer] + +\definebtx + [duane] + [default=, + specification=duane, + authorconversion=normal] + +\definebtx + [duane:list] + [duane] + +\definebtx + [duane:list:author] + [duane:list] + +\definebtx + [duane:list:image] + [duane:list] + +\definebtxrendering + [duane] + [specification=duane, + dataset=duane, + method=dataset, + numbering=no, + criterium=all] + +\stopbuffer + +\cindex{definebtxdataset} +\cindex{usebtxdataset} +\cindex{definebtx} +\cindex{definebtxrendering} + +\typeTEXbuffer \getbuffer + +Instead of for instance \TEXcode {apa} we create a specification named \TEXcode +{duane}. Because categories are rendered with a setup, we can define the +following: + +\startbuffer +\startsetups btx:duane:list:image + \tbox \bgroup + \bTABLE[offset=1ex] + \bTR + \bTD[ny=4] + \dontleavehmode + \externalfigure[\btxflush{url_thumb}][width=3cm] + \eTD + \bTD \btxflush{title} \eTD + \eTR + \bTR + \bTD \btxflush{author} \eTD + \eTR + \bTR + \bTD \btxflush{description} \eTD + \eTR + \bTR + \bTD + \goto{high res variant}[url(\btxflush{url_image})] + \eTD + \eTR + \eTABLE + \egroup +\stopsetups + +\placebtxrendering[duane][criterium=all] +\stopbuffer + +\cindex{startsetups} +\cindex{stopsetups} +\cindex{placebtxrendering} +\cindex{btxflush} + +\typeTEXbuffer \getbuffer + +An alternative rendering is: + +\startbuffer +\startsetups btx:duane:list:image + \bgroup + \bTABLE[offset=1ex] + \bTR + \bTD + \dontleavehmode + \goto{\externalfigure[\btxflush{url_thumb}][width=3cm]} + [url(\btxflush{url_image})] + \eTD + \bTD + \bold{\btxflush{title}} + \blank + \btxflush{description} + \blank [3*line] + \btxflush{author} + \eTD + \eTR + \eTABLE + \egroup +\stopsetups + +\placebtxrendering[duane] +\stopbuffer + +\cindex{startsetups} +\cindex{stopsetups} +\cindex{placebtxrendering} +\cindex{btxflush} + +\typeTEXbuffer \getbuffer + +We only get the second rendering because we specified \TEXcode {criterium} as +\TEXcode {all}. Future version of \CONTEXT\ will probably provide \Index{sorting} +options and ways to plug in additional functionality. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-overviews.tex b/doc/context/sources/general/manuals/publications/publications-overviews.tex new file mode 100644 index 000000000..17b98cc3c --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-overviews.tex @@ -0,0 +1,39 @@ +\environment publications-style + +\startcomponent publications-overviews + +\startchapter[title=Bibliography,reference=ch:biblio] + +\setupbtxrendering + [default] + [pagestate=start, + before=, + after=] + +\placelistofpublications + +\stopchapter + +\startchapter[reference=ch:listoftables,title=List of tables] + \placelistoftables [criterium=all] +\stopchapter + +\startchapter[reference=ch:indexofauthors,title=Index of names] + \placeregister[indexofauthors] [criterium=all,compress=yes] +\stopchapter + +\startchapter[reference=ch:index,title=Index of subjects] + \placeindex [criterium=all,compress=yes] +\stopchapter + +\startchapter[title=Hashed authors] + +\start + \small + \small + \showbtxhashedauthors +\stop + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-performance.tex b/doc/context/sources/general/manuals/publications/publications-performance.tex new file mode 100644 index 000000000..ec358dfc9 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-performance.tex @@ -0,0 +1,46 @@ +\environment publications-style + +\startcomponent publications-performance + +\startchapter[title=Performance] + +The move from external \BIBTEX\ processing to internal processing has the +advantage that we stay within the same run. In the traditional approach we had +roughly the following steps: + +\startitemize[packed] +\startitem + In the first \CONTEXT\ run information is collected and written to file. +\stopitem +\startitem + fter the first run the \BIBTEX\ program converts that file to another + one, a so called \type {bbl} file with \TEX\ commands. +\stopitem +\startitem + Successive runs use that file for typesetting references and producing + lists of publications that are reffered to. +\stopitem +\stopitemize + +In the \MKIV\ approach the bibliographic database is loaded in memory each run +and processing also happens each run. On paper this looks less efficient but as +\LUA\ is quite fast, in practice performance is much better. + +Probably most demanding is the treatment of authors as we have to analyze names, +split multiple authors and reassemble firstnames, vons, surnames and juniors. +When we sort by author sorting vectors have to be made which also has a penalty. +However, in practice the user will not notice a performance degradation. We did +some tests with a list of 500.000 authors, sorted them and typeset them as list +(producing some 5400 dense pages in a small font and with small margins). This is +typical one of these cases where using \LUAJITTEX\ saves quite time. On my +machine it took just over 100 seconds to get this done. Unfortunately not all +operating systems performed equally well: 32 bit versions worked fine, but 64 bit +\LINUX\ either crashed (stalled) the machine or ran out of memory rather fast, +while \MACOSX\ and \WINDOWS\ performed fine. In practice you will never run into +this, unless you produce massive amounts of bibliographic entries. \LUAJIT\ has +some benefits but also some drawbacks. In practice you will not run into these +problems. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-quick-example.tex b/doc/context/sources/general/manuals/publications/publications-quick-example.tex new file mode 100644 index 000000000..14f70960f --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-quick-example.tex @@ -0,0 +1,16 @@ +\usebtxdataset[mkiv-publications.bib] + +\starttext + +\startbodymatter +a citation: \cite[article,book] +\stopbodymatter + +\startbackmatter + \startchapter[title=Bibliography] + \placelistofpublications + \stopchapter +\stopbackmatter + +\stoptext + diff --git a/doc/context/sources/general/manuals/publications/publications-quick.tex b/doc/context/sources/general/manuals/publications/publications-quick.tex new file mode 100644 index 000000000..930203a38 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-quick.tex @@ -0,0 +1,44 @@ +\environment publications-style + +\startcomponent publications-quick + +\startchapter + [reference=ch:quick, + list={Quick start}, + title={\Index{Quick start}, for the impatient}] + +\cindex{usebtxdataset} +\cindex{cite} +\cindex{placelistofpublications} + +Without \emphasis {any} explanation: + +\typeTEXfile + {publications-quick-example.tex} + +\startcombination[c=2,r=1,distance=\emwidth] + \startcontent + \typesetfile + [publications-quick-example.tex] + [width=.5\dimexpr\textwidth-\emwidth\relax,frame=on,page=1] + \stopcontent + \startcaption + bodymatter + \stopcaption + \startcontent + \typesetfile + [publications-quick-example.tex] + [width=.5\dimexpr\textwidth-\emwidth\relax,frame=on,page=2] + \stopcontent + \startcaption + backmatter + \stopcaption +\stopcombination + +This example demonstrates that the basic usage in the production of bibliography +citations and lists is rather simple. However, once the user starts asking for +particular customizations, then things can get quite complicated rather quickly. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-rendering.tex b/doc/context/sources/general/manuals/publications/publications-rendering.tex new file mode 100644 index 000000000..546dc2f20 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-rendering.tex @@ -0,0 +1,549 @@ +\environment publications-style + +\startcomponent publications-rendering + +\startchapter[title=Renderings,reference=ch:renderings] + +\startsection + [reference=sec:styles, + title={Generating lists of publications}] + +A list of publications can be rendered at any place in the document, and multiple +renderings can appear under certain limitations (according to \Index {scope}). +The specification introduced previously defines the style of the rendering as +well as what data it will contain. + +If you want to see what publications are in the database, the easiest way is to +ask for a complete list: + +\startbuffer +\usebtxdataset % illustrated again here + [example] % although already loaded + [mkiv-publications.bib] % in the previous chapter + +\definebtxrendering + [example] % named rendering + [apa] % parent namespace + [dataset=example, + group=examples] % group will be presented later + +\placelistofpublications % aka \placebtxrendering + [example] % rendering defined above + [method=dataset] % i.e. all entries +\stopbuffer + +\cindex{definebtxrendering} +\cindex{placelistofpublications} +\cindex{placebtxrendering} + +\typeTEXbuffer + +The commands \Cindex {placelistofpublications} (that is just a synonym for +\Cindex {placebtxrendering}) refer to a named rendering and accept a list of +options (inherited from \Cindex {setupbtxrendering}). When applied to a named +dataset (other than \TEXcode {default}), a named rendering needs to be associated +through \Cindex {definebtxrendering} as is done here. + +Note that the define shown above explicitly inherits from a rendering named +\TEXcode {apa} that was itself defined when loading the specification file. +\startfootnote The rendering parent \index {style+APA}\TEXcode {[apa]} sets the +parameters: \TEXcode {specification=apa,} \TEXcode {sorttype=authoryear,} and +\TEXcode {numbering=no,} described below. It also sets various list parameters in +a protected \TEXcode {apa} namespace to produce a \quote {hanging} bibliography +list. \stopfootnote Had this inheritance not been specified, the new rendering +would inherit default, minimal settings. This notion of inheritance will be +further illustrated later. + +The bibliography list rendering of our example dataset, following the \index +{style+APA}APA style, is: + +\getbuffer + +The rendering is a list whose appearance can be tuned, as any list in \CONTEXT. +It is somewhat more complex to manage, though, because we can have not only many +different standards but also many fields that can be set up. This means that +there are several commands involved. As we saw demonstrated above, a rendering is +defined and setup using the commands: + +\cindex{definebtxrendering} + +\showsetup{definebtxrendering} + +\cindex{setupbtxrendering} + +\showsetup{setupbtxrendering} + +\startbuffer + \showrootvalues[btxrendering] + \showinstancevalues[btxrendering][default] + \usebtxdefinitions[apa] % needed for: + \showinstancevalues[btxrendering][apa] +\stopbuffer + +\typebuffer \getbuffer + +A rendering is then placed using \Cindex {placebtxrendering}, a \CONTEXT\ command +that accepts the same arguments as for its setup. Using \TEXcode +{method=dataset}, as above, one renders the entire contents of the dataset. +Normally, however, one would not use this \TEXcode {method} and place only a +selection of entries that are to be used in the document, whereas the dataset may +very well contain many other, unused references. The \TEXcode {method=global} or +\TEXcode {method=local} option can be used to specify if this use is to be global +for the entire document or else local to a structure element such as a part or a +chapter. + +\cindex{placebtxrendering} + +\showsetup{placebtxrendering} + +\cindex{placelistofpublications} + +\showsetup{placelistofpublications} + +The rendering is a \TEXcode {list} and this reference list is numbered. These +numbers can be displayed, or not, depending on the bibliography style +specification through the use of the \index {numbering}\TEXcode {numbering=yes} +or \TEXcode {no} parameter values. The \index {style+APA}APA style, illustrated +above, normally does not number the bibliography list. + +The reference list is also \index {sorting}sorted, controlled by the parameter +\TEXcode {sorttype}; here \TEXcode {sorttype=authoryear}, appropriate for the +\index {style+APA}APA style, \Index {sorting} first by author list, then by +publication year, then by title, finally by page. One can sort the list in many +ways: for example \TEXcode {sorttype=index} will render the list in the order in +which it was loaded into the dataset (see \in {table} [tab:sorttype] for an +explanation of list sorting schemes). + +\startplacetable [location=force, + title={\TEXcode {sorttype=}}, + reference=tab:sorttype] +\index{sorting} +\starttabulate [|Tp(5.5em)|p(.75\textwidth)|] +\HL +\NC default\\none\\cite\\list +\NC render the list in the order in which it was built, + that is, in the order that references were selected from the dataset for + inclusion in the list. \NC \NR +\HL +\NC dataset\\index +\NC sort the list according to the dataset index, that is, in the order in that + references were added to the dataset. \NC \NR +\HL +\NC reference +\NC sort the list in alphabetical order of the citation \Index{tag}s of the + dataset. Note that all entries missing tags get assigned the dataset index as + their tag. \NC \NR +\HL +\NC key +\NC sort the list in alphabetical order of the entry field \TEXcode {key} + (traditionally used in \BIBTEX\ as an alternate sorting key). Falls back on + the dataset index if no such field is present. \NC \NR +\HL +\NC short +\NC sort the list in alphabetical order of the short tag (first three letters + of the author name or first letter of the first three authors followed by + the last two digits of the year). \NC \NR +\HL +\NC authoryear +\NC sort the list in alphabetical order of the authors (or editors or publisher), + then by publication year, then by title (or by journal and volume) and + finally by page. \NC \NR +\stoptabulate +\stopplacetable + +As a concrete example, the rendering named \TEXcode {example} above inherits from +the rendering instance named \TEXcode {apa} that is defined in the specification +file as: + +\cindex{definebtxrendering} + +\startTEX +\definebtxrendering + [apa] + [specification=apa, + sorttype=authoryear, + numbering=no] +\stopTEX + +\startaside +A more subtle characteristic of renderings is that one generally would not want a +bibliography list to appear redundantly in a document as that would be confusing, +unless of course it is desired that elements of the list reappear in later lists, +for example when placing partial bibliographies at the end of each chapter and a +complete bibliography list at the end of a book. One must specify \TEXcode +{repeat=yes} in order to get multiple renderings of a bibliography list; +otherwise, as they appear, entries get marked as placed and will be inhibited +from being placed again elsewhere. +\stopaside + +All renderings of bibliography lists such as the one shown earlier in this +section also depend on a set of general list parameters that apply to each +individual entry (a cited publication), as for any list item in \CONTEXT. These +can be adjusted through the command \Cindex {setupbtxlist} (further described in +\in {section} [sec:list], below). As an example, the \TEXcode {apa} specification +file includes: + +\cindex{setupbtxlist} + +\startTEX +\setupbtxlist + [apa] + [alternative=paragraph, + width=fit, + distance=.5em, + margin=3em] +\stopTEX + +Such settings (yielding a hanging list that would be inappropriate with a +numbered bibliography list) get inherited from the \TEXcode {apa} namespace in +the rendering that we named \TEXcode {example} above. + +Let's try a new example (using a file taken from the \index {TUG bibliography +archive}\goto {TUG bibliography archive} +[url(http://ftp.math.utah.edu/pub/tex/bib/index.html)]): \startfootnote \index +{template.bib} The file \TEXcode {template2.bib} is simply a copy of \TEXcode +{template.bib} that has been cleaned|-|up to remove the empty entries. +\stopfootnote + +\startbuffer +\definebtxdataset[template] +\usebtxdataset [template][template2.bib] + +\loadbtxdefinitionfile[aps] +\definebtxrendering + [template] + [aps] + [dataset=template, + group=examples] + +\placelistofpublications + [template] + [method=dataset] +\stopbuffer + +\cindex{definebtxdataset} +\cindex{usebtxdataset} +\cindex{loadbtxdefinitionfile} +\cindex{definebtxrendering} +\cindex{placelistofpublications} + +\typeTEXbuffer + +Here, the new rendering is defined to inherit explicitly from a rendering named +\index {style+APS}\TEXcode {aps} (whose specification is loaded but not activated +here). Notice, in particular, compared to the previous rendering example, that +the list is numbered and that there is no hanging margin (it uses the standard +list \TEXcode {alternative=b}): + +\getbuffer + +The \Index {numbering} of the references are unique and pick|-|up from where the +previous numbering stops (the first example contains 33 references, although this +numbering is not displayed). This behavior can be \TEXcode {method=global} for +the entire document, or else \TEXcode {method=local}, limited to a structural +element such as a chapter or a part. Furthermore, one can associate renderings +into particular number groups, effectively isolating them from any other +renderings. For example, as seen above in the rendering definitions, the present +manual uses: + +\cindex{setupbtxrendering} + +\startTEX +\setupbtxrendering[example] [group=examples] +\setupbtxrendering[template][group=examples] +\stopTEX + +thus setting the numbering of the group \TEXcode {examples} apart from the +numbering of the dataset \TEXcode {default} and its named rendering that contains +this manual's own bibliography (that will be placed later, on \at {page} +[ch:biblio]). + +\stopsection + +\startsection + [reference=sec:styles, + title={Rendering styles, or more on specifications}] + +The default rendering style implemented in the \MKII\ module was loosely based on +the \index {style+APA}APA standard. In contrast, we made a design choice in the +present \MKIV\ system to provide a very minimal \TEXcode {default} style, and one +should not expect much from this default: in fact, it only recognizes \type +{article} and \type {book} entries. A user requiring a more complete rendering +will want to explicitly load another style file. One such complete specification, +illustrated above and appropriately named \index {style+APA}\TEXcode {apa}, is +described in the \cite [title] [default::APA2010] \cite [num] [default::APA2010]. + +\startaside +\emphasis {A note on the \index {style+APA}APA style:} We get the strong +impression that the APA bibliography style standard was made with the implicit +assumption that manual intervention would be involved in the editing and +production process; It has been an arduous task to create a system capable of +fully conforming to these specifications. + +Furthermore, we note that it has sometimes been argued that a numbered citation +system and bibliography list is supposedly superior to the author|-|year scheme +as is employed in the \index {style+APA}APA style (amongst others); indeed, +handling numbered citations is certainly much easier from the point of view of +the programmer of an automated typesetting system such as \TEX. Yet many find +that the longer author|-|year citations can be of great use to the reader (as +well as the writer) so we take no stand in this debate and provide both +possibilities. + +We have made (and continue to make) a great effort to scrupulously respect the +\index {style+APA}APA style in the so|-|named rendering. Yet be warned that very +few editors and publishers in fact follow this style exactly so some +customization will always be required. +\stopaside + +In addition to the APA specification, there are many prescribed styles to render +bibliographic descriptions that can be programmed as standards. Alternatives to +\index {style+APA}\TEXcode {specification=apa} might be \index +{style+MLA}\TEXcode {mla}, \index {style+Chicago}\TEXcode {chicago}, \index +{style+Harvard}\TEXcode {harvard}, \index {style+IEEE}\TEXcode {ieee}, \index +{style+APS}\TEXcode {aps} (commonly used in the physical sciences), \index +{style+Vancouver}\TEXcode {vancouver} (used in the biological sciences), or many +others. At this time, we only provide two description files, with \index +{style+APS}\TEXcode {aps} being an example\startfootnote The \index +{style+APS}APS style attempts to be very compact, providing complete yet minimal +information, in contrast to the \index {style+APA}APA style which is rather +verbose. \stopfootnote of a number|-|based rather than an authoryear|-|based +scheme; more style schemes may be added in the future and the customization of a +rendering style will be described in a later chapter. + +The rendering style usually also implies a particular bibliography list \Index +{sorting} scheme as well as the use of a particular citation style. Indeed, the +rendering of bibliography lists and references to it are intimately coupled. This +question will be explained a bit later. The \index {style+APA}APA style, for +example, specifies that the bibliography list be sorted by author and then by +year, then by title. The list is not numbered (references are cited by author and +year). Note, however, as can be seen from the two examples shown above that the +references were indeed assigned numbers even though they are not displayed in the +\index {style+APA}\TEXcode {apa} rendering (the user can easily choose to display +these numbers, if desired). + +\stopsection + +\startsection + [list={Bibliography list scope}, + title={Bibliography list \Index{scope}}] + +A single dataset can by used with multiple renderings. Although these renderings +may illustrate different styles (as here for the purpose of demonstration in a +manual on bibliographies), this would not be a coherent choice for a document +that would normally employ a single bibliography style. + +The most obvious use of multiple renderings (employing a single specification) is +the placement of bibliography lists localized by structure elements: parts, +chapters in a book, sections, etc. through the option \TEXcode +{criterium=chapter}, for example. This can be setup using: + +\cindex{setupbtxrendering} + +\startTEX +\setupbtxrendering + [default] + [repeat=yes, + continue=yes, + method=global] +\stopTEX + +followed at the end of each chapter by + +\cindex{placelistofpublications} + +\startTEX +\placelistofpublications + [criterium=chapter] +\stopTEX + +The numbering might alternately be made local through the option \TEXcode +{method=local}. If desired, the reference numbers can also get prefixed: + +\cindex{setupbtxlist} + +\startTEX +\setupbtxlist + [default] + [prefix=yes, + width=1cm] +\stopTEX + +A bibliography list rendering placed at a single location, at the end of a book, +for example, can also be easily split into structural parts. The following code +(given without any explanation) illustrates this idea nicely: + +\cindex{placelistofpublications} + +\startTEX +\startbackmatter + \startchapter [title=Bibliography,number=no,incrementnumber=no] + \startsubject [title=Introduction] + \placelistofpublications + [criterium=reference,reference=introduction] + \stopsubject + \dorecurse{12} { + \startsubject [title={Chapter #1}] + \placelistofpublications + [criterium=bodypart:chapter,reference=#1] + \stopsubject + } + \stopchapter +\stopbackmatter +\stopTEX + +Note, as the above demonstrates, that the list of bibliography citations for +\emphasis {any} referenced structural element can be placed \emphasis {anywhere} +in the document, not simply within the structural element itself. + +\stopsection + +\startsection[title=Language] + +Bibliography lists (and citations in the text, see below) are rendered in the +language of the document (\Cindex {mainlanguage}). However, a bibliography entry +can contain a \TEXcode {language=} field and this can be used (if present), +depending on the specification, in the rendering and hyphenation of the \TEXcode +{title}, for example. + +One might choose to override this behavior and impose a single language for all +bibliography entries (as well as for all other \CONTEXT\ constructs) using +\Cindex {setupdelimitedtext} \TEXcode {[language=global]}. + +Since this directive is general for all delimited text in \CONTEXT\ and is not +specific to bibliographies, one can apply it to force a particular language +within a unique section, as in: + +\cindex{setupdelimitedtext} +\cindex{placelistofpublications} + +\startTEX +\startsection[title=Bibliografía] + \setupdelimitedtext[language=es] + \placelistofpublications +\stopsection +\stopTEX + +% to Hans: This currently does not work! +% to Alan: I need an example! + +The language setting also influences the sorting of \UTF\ strings, in particular +authors and titles. + +\startplacetable [title={\cindex{setupdelimitedtext}\TEXcode{\setupdelimitedtext[language=…]}}] + \starttabulate [|Tl|p(.7\textwidth)|] + \NC language= \NC \NC \NR + \HL + \NC {\it<blank>} \NC (the default) use the current active language; \NC \NR + \NC local \NC respect local language directives (such as the + entry's \TEXcode {language={…},} field, if present + and managed by the rendering specification) \NC \NR + \NC global \NC impose the main document language; \NC \NR + \NC en, de, nl, + \unknown \NC impose the specified language. \NC \NR + \HL + \stoptabulate +\stopplacetable + +\cindex {setupdelimitedtext} +\showsetup[setupdelimitedtext] + +\startsubsubject[title=Translated titles] + +Going beyond this handling of punctuation, labels and sorting, we have also +introduced an entirely new feature, allowing for dataset entries to contain +fields describing translated titles, for example. This is particularly useful +when including citations to references published in languages other than the +document language. + +Below is an example including \emphasis{three} languages: \startfootnote In this +reference, the \TEXcode {title} and the \TEXcode {booktitle} are in different +languages and the \TEXcode {language = {french},} field refers to the cited text. +Both titles would have been rendered using French hyphenation rules had this not +been overridden by including the switch \TEXcode {\de} that otherwise should be +avoided in a database. The solution used here is sloppy, but fortunately, a +complicated situation such as this is not very common. +\stopfootnote + +% We could have +% booktitle:de = {Die ...}, +% +% but what simple logic could be used to indicate choosing this title? +% The present case could, perhaps should, have language = {german}, but this +% would simply switch the problem to title = {\fr Principes ...}, + +\startbuffer +\startbuffer[leibniz] +@INCOLLECTION{Leibniz1885, + author = {Leibniz, G. W.}, + title = {Principes de la nature et de la grâce fondés en raison, 1714}, + title:en = {Principles of Nature and Grace Founded in Reason}, + booktitle = {\de Die Philosophischen Schriften von Gottfried Wilhelm Leibniz}, + booktitle:en = {The Philosophical Writings of Gottfried Wilhelm Leibniz}, + editor = {Gerhardt, C. G.}, + publisher = {Weidmann}, + year = {1885}, + volume = {6}, + chapter = {8}, + pages = {598–606}, + address = {Berlin}, + language = {french}, +} +\stopbuffer +\stopbuffer + +\typeTEXbuffer \getbuffer + +\startbuffer +\usebtxdataset [leibniz][leibniz.buffer] +\definebtxrendering[leibniz][apa][dataset=leibniz] +\placebtxrendering [leibniz][group=examples,method=dataset] +\stopbuffer + +with + +\typeTEXbuffer + +that gets rendered as: + +\getbuffer + +In the \index {style+APA}APA bibliography style, the original reference title is +listed followed by the translated title (within square brackets), the translation +chosen being that of the \Cindex {mainlanguage} of the document (if present in +the entry, of course). In other bibliography styles, this feature might not be +implemented or may be ignored. + +\stopsubsubject + +\startsubsubject + [title=Multilingual bibliographies] + +The present handling of languages is only the beginning, and these features will +be developed further in the future: multilingual typesetting being one of the +great strengths behind \CONTEXT. + +\stopsubsubject + +\stopsection + +\startsection + [title=Page index] + +The list renderings can also include a page index of citations to each entry. +This can be enabled using the parameter \TEXcode {pagestate}: + +\cindex{setupbtxrendering} + +\startTEX +\setupbtxrendering [pagestate=start] +\stopTEX + +As this is more of a subject related to the citation mechanism, it will be +described in the following chapter (see \in {section} [sec:index], \at {p.} +[sec:index]). + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-style.tex b/doc/context/sources/general/manuals/publications/publications-style.tex new file mode 100644 index 000000000..5283b9c61 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-style.tex @@ -0,0 +1,346 @@ +\startenvironment publications-style + +\dontcomplain + +\setupbodyfont + [dejavu,10pt] + +\definecolor[fore:one] [darkmagenta] +\definecolor[fore:two] [darkcyan] +\definecolor[fore:three][darkyellow] + +% \definecolor[back:one][.85(darkblue,white)] +% \definecolor[back:two][.85(darkcyan,white)] +\definecolor[back:one] [.90(darkyellow,white)] +\definecolor[back:two] [.90(darkyellow,white)] +\definecolor[back:three][.90(darkblue,white)] + +\setuphead + [chapter] + [header=high, + style=\bfc] + +\setuphead + [section,subject] + [style=\bfb] + +\setuphead + [subsection,subsubject] + [style=\bfa] + +\setuphead + [chapter,section,subject,subsection,subsubject] + [color=fore:one] + +\setupheader + [color=fore:one] + +\setuplayout + [topspace=1.5cm, + bottomspace=1cm, + width=middle, + height=middle] + +\setupfootertexts + [pagenumber] + +\setupheadertexts + [chapter] + +\setupnotes + [location=none] + +\setupnotation + [way=bychapter] + +\startsetups chapter:after + \ifcase\rawcountervalue[footnote]\relax + \or + \startsubject[title=Footnote] + \placefootnotes + \stopsubject + \else + \startsubject[title=Footnotes] + \placefootnotes + \stopsubject + \fi +\stopsetups + +\setuphead + [chapter] + [aftersection=\setups{chapter:after}] + +\setupwhitespace + [big] + +% All this syntax highlighting doesn't look good but Alan likes it, so: + +\definetype[BTXcode][option=TEX] +\definetype[XMLcode][option=XML] +\definetype[TEXcode][option=TEX] +\definetype[LUAcode][option=LUA] +\definetype[MPcode] [option=MP] + +\definetyping[BTX] [option=LUA] % we don't have a highlight yet + +\setuptyping + [keeptogether=yes] + +% I guess that Hans finds the syntax highlighting to be distracting ... Indeed, +% too much color. + +\startmode[atpragma] + + \setuptype [option=,color=fore:two] + \setuptype[BTXcode][option=,color=fore:two] + \setuptype[XMLcode][option=,color=fore:two] + \setuptype[TEXcode][option=,color=fore:two] + \setuptype[LUAcode][option=,color=fore:two] + \setuptype[MPcode] [option=,color=fore:two] + + \setuptyping [option=,color=fore:one] + \setuptyping[BTX][option=,color=fore:one] + \setuptyping[XML][option=,color=fore:one] + \setuptyping[TEX][option=,color=fore:one] + \setuptyping[LUA][option=,color=fore:one] + \setuptyping[MP] [option=,color=fore:one] + +\stopmode + +% \setupinteraction +% [state=start, +% style=bold, +% color=fore:two, +% contrastcolor=fore:two] + +\setupinteraction + [state=start, + style=, + color=, + contrastcolor=] + +\setupalign + [verytolerant] + +\definehighlight + [emphasis] + [style=italic] + +% This bit of MP magic keeps the text aligned and puts the left frame in the margin. + +\startuseMPgraphic{mpos:region:aside} + for i=1 upto nofmultipars : + multipars[i] := multipars[i] leftenlarged ExHeight ; + endfor ; + draw_multi_pars ; + draw_multi_side ; +\stopuseMPgraphic + +\definetextbackground + [framedbg] + [location=paragraph, + before=\blank, + after=\blank, + mp=mpos:region:aside, + topoffset=.5ex, + leftoffset=0pt, + rightoffset=1ex, + bottomoffset=.5ex, + frame=off, + leftframe=on, + frameoffset=1ex, + rulethickness=2pt, + framecolor=fore:two, + background=color, + backgroundcolor=back:two] + +\definetextbackground + [aside] + [framedbg] + [framecolor=fore:one, + backgroundcolor=back:one] + +\setupbtxrendering + [before={\startframedbg\blank[disable]}, + after={\blank[back]\stopframedbg}] + +% HH: low level, no high level switch (yet): + +\setnewconstant\kindofpagetextareas 1 + +\defineregister + [indexofauthors] + +\definebtxregister + [authors] + [field=author, + register=indexofauthors, + method=always, + dataset={default,tugboat,boekplan}, + alternative=invertedshort] + +% the \textbackslash variant doesn't always work out well with inline verbatim as \tt is +% something else .. also, following that by some arguments in \type is messy +% +% bad: \cindex {cite}\TEXcode{\cite[field][tag]} + +\define [1] \Index {\index {#1}#1} +\define [1] \tindex{\index [#1]{\tt#1}} +\define [1] \Tindex{\tindex{#1}{\tt#1}} +\define [1] \cindex{\expanded{\index [#1]{\TEXcode{\expandafter\string\csname#1\endcsname}}}} % bah +\define [1] \Cindex{\expanded{\cindex{#1}{\TEXcode{\expandafter\string\csname#1\endcsname}}}} % bah + +% hm + +\define [2] \name {\btxregisterauthor{#1 #2}\indexofauthors{#1, #2}} +\define [2] \Name {\name{#1}{#2}#1} + +\setupnote + [footnote] + [next={ }] % Why should this be necessary? + +\setupfloat + [table] + [default={here,force}] + +\setupcaption + [table] + [location=top] + +\setuplist + [table] + [interaction=all, + alternative=c] + +\usemodule[abr-02] +\usemodule[set-11] + +\logo [BibTeX] {Bib\TeX} + +\startmode[export] + + \setupbackend + [export=yes]%, + + % \setupexport + % [hyphen=yes, + % width=60em] + + \setuptagging + [state=start] + + % HH: bah: + + \setupinteraction [option=bookmark] + \setupinteractionscreen [option=bookmark] + \placebookmarks [chapter,title,section,subsection] + +\stopmode + +\setupinteraction + [title={\documentvariable{title}}, + subtitle={\documentvariable{subtitle}}, + author={\documentvariable{author}}] + +\usemodule[setups-basics] + +\loadsetups[i-context] + +% \setupframedtext +% [setuptext] +% [rulethickness=2pt, +% framecolor=fore:three, +% leftframe=on, +% frame=off, +% width=\dimexpr\hsize\relax, +% background=color, +% backgroundcolor=back:three] + +\definetextbackground + [mysetuptext] + [framedbg] + [framecolor=fore:three, + backgroundcolor=back:three] + +\startsetups xml:setups:start + \starttextbackground[mysetuptext] +\stopsetups + +\startsetups xml:setups:stop + \stoptextbackground +\stopsetups + +% Since this is a manual about bibliographies, let us use citations... + +\startbuffer [bibliography] +@Book{Ierusalimschy2006, + author = {Ierusalimschy, R.}, + title = {Programming in Lua}, + year = {2006}, + publisher = {Lua.org}, + isbn = {8590379817}, + url = {http://www.lua.org/pil/contents.html}, +} + +@Book{APA2010, + title = {Publication Manual of the American Psychological Association}, + year = {2010}, + edition = {Sixth}, + address = {Washington, DC}, + publisher = {American Psychological Association}, + note = {291 pages}, + ISBN = {1-4338-0559-6 (hardcover)}, + url = {http://www.apa.org/books/}, +} + +@Article{Patashnik1988, + title = {Bib\TEX ing}, + author = {Patashnik, Oren}, + year = {1988}, + month = {February}, + day = {8}, + url = {https://www.ctan.org/tex-archive/biblio/bibtex/base/btxdoc..pdf}, +} + +@Article{Markey2009, + title = {Tame the BeaST}, + subtitle = {The B to X of Bib\TEX}, + author = {Markey, Nicolas}, + year = {2009}, + month = {October}, + day = {11}, + url = {http://tug.ctan.org/info/bibtex/tamethebeast/ttb_en.pdf}, +} + +@Book{vanLeunen1992, + title = {A Handbook for Scholars}, + author = {van Leunen, Mary-Claire}, + year = {1992}, + edition = {revised}, + publisher = {Oxford University Press}, + address = {New York}, +} + +@BOOK{Darwin1859, + author = {Darwin, C.}, + year = {1859}, + title = {On the Origin of Species by Means of Natural Selection, or The Preservation + of Favoured Races in the Struggle for Life}, + publisher = {John Murray}, + address = {London} +} +\stopbuffer + +\usebtxdataset + [bibliography.buffer] + +% also used: + +%\definebtxdataset +% [tugboat] + +%\usebtxdataset +% [tugboat] +% [tugboat.bib] + +\stopenvironment diff --git a/doc/context/sources/general/manuals/publications/publications-titlepage.tex b/doc/context/sources/general/manuals/publications/publications-titlepage.tex new file mode 100644 index 000000000..dfc53419a --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-titlepage.tex @@ -0,0 +1,39 @@ +\environment publications-style + +\startcomponent publications-titlepage + +\startMPpage + + StartPage ; + + picture pic ; pic := image ( + path pth ; pth := ((0,0) for i=1 step 2 until 20 : -- (i,1) -- (i+1,0) endfor) ; + for i=0 upto 9 : draw pth shifted (0,2*i) ; endfor ; + ) ; + + picture btx ; btx := textext("\ssbf\WORDS{\getvariable{document}{title}}") ; + picture ctx ; ctx := textext("\ssbf\WORDS{\getvariable{document}{subtitle}}") ; + picture dtx ; dtx := textext("\ssbf \getvariable{document}{author}") ; + + pic := pic shifted - llcorner pic ; + btx := btx shifted - llcorner btx ; + ctx := ctx shifted - llcorner ctx ; + dtx := dtx shifted - llcorner dtx ; + + pic := pic xysized (PaperWidth,PaperHeight) ; + btx := btx xsized (2PaperWidth/3) shifted (.25PaperWidth,.225PaperHeight) ; + ctx := ctx xsized (2PaperWidth/3) shifted (.25PaperWidth,.150PaperHeight) ; + dtx := dtx xsized (2PaperWidth/3) shifted (.25PaperWidth,.075PaperHeight) ; + + fill Page withcolor \MPcolor{fore:two} ; + + draw pic withcolor \MPcolor{fore:one} ; + draw btx withcolor \MPcolor{lightgray} ; + draw ctx withcolor \MPcolor{lightgray} ; + draw dtx withcolor \MPcolor{lightgray} ; + + StopPage ; + +\stopMPpage + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-tracing.tex b/doc/context/sources/general/manuals/publications/publications-tracing.tex new file mode 100644 index 000000000..e48e5d655 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-tracing.tex @@ -0,0 +1,107 @@ +\environment publications-style + +\startcomponent publications-tracing + +\startchapter + [title=Tracing] + +There are several tracing options. If you want to see where a citations refers to +and where a list entry point back to, you can say: + +\startTEX +\enabletrackers[publications.crosslinks] +\stopTEX + +This injects markers in both places. One list entry can point to multiple +citations. The other tracers a more for debugging and can generate lots of +messages. + +\startTEX +publications +publications.authorhash +publications.cite +publications.cite.missing +publications.cite.references +publications.detail +publications.duplicates +publications.match +publications.sorters +publications.suffixes +\stopTEX + +You can also trace the databases. Take this one: + +\startbuffer +\startbuffer[phony] +@comment { warning : + Hello Allan! + How are you doing today? +} + +@CoMMeNT { message : + Hello Allan! + How are you doing today? +} + +@comment { + all kind of crap +} + +@Article{Myarticle, + Title = {My title}, + Author = {Myself, Me}, + Journal = {My favorite journal}, + Year = {2014}, + Pages = {1}, +} + +@Foo{foo, + Goo = goo, +} +\stopbuffer +\stopbuffer + +\typeBTXbuffer \getbuffer + +\startbuffer +\usebtxdataset [phony] [phony.buffer] +\stopbuffer + +When we load this database (buffer) with: + +\typeTEXbuffer \getbuffer + +We get this on the console and in the log + +\starttyping +publications > adding bib data to set 'phony' from source 'phony' +publications > phony > warning : Hello Allan! +publications > phony > warning : How are you doing today? +publications > phony > message : Hello Allan! +publications > phony > message : How are you doing today? +\stoptyping + +You can use this feature to add warnings to your database for entries that you +need to check. + +You can also use comment to hide entries: + +\startBTX +@comment { + + @article{Hobby1999, + author = {Hobby, John D.}, + year = {1999}, + title = {Introduction to MetaPost}, + journal = {Eutupon}, + volume = {2}, + month = {April}, + pages = {39-53}, + } + +} +\stopBTX + +\stopchapter + +\stopcomponent |