| 1 | [[PageOutline(2-5,Contents,pullout)]] |
| 2 | |
| 3 | = A !BibTex Cite Plugin |
| 4 | |
| 5 | == Description |
| 6 | |
| 7 | [http://en.wikipedia.org/wiki/BibTeX BibTex] is for formatting lists of bibliographic references. |
| 8 | |
| 9 | This plugin provides the ability to cite from common bibtex (*.bib) files. |
| 10 | |
| 11 | The plugin can use bibtex files out of : |
| 12 | * a repository (svn, git, mercurial) |
| 13 | * a wiki page |
| 14 | * a Wiki-Attachment |
| 15 | * or an external website. |
| 16 | |
| 17 | If a wiki page called !BibTex exists, the page is loaded automatically by ''''!BibRef()'''' and used as standard library. |
| 18 | |
| 19 | Make sure to put bibtex entries into a Code Block when you use them from a wiki page. |
| 20 | |
| 21 | The command structure is inspired by the reference and bibtex system in latex. This should make it easy to make this plugin compatible with existing trac - latex plugins. |
| 22 | |
| 23 | == Bugs/Feature Requests |
| 24 | |
| 25 | Existing bugs and feature requests for TracBibPlugin are |
| 26 | [query:status!=closed&component=TracBibPlugin&order=priority here]. |
| 27 | |
| 28 | If you have any issues, create a |
| 29 | [/newticket?component=TracBibPlugin&owner=Amfortas new ticket]. |
| 30 | |
| 31 | [[TicketQuery(component=TracBibPlugin&group=type,format=progress)]] |
| 32 | |
| 33 | == Download and Source |
| 34 | |
| 35 | Download the [download:tracbibplugin zipped source], check out from [/svn/tracbibplugin using Subversion], or [source:tracbibplugin browse the source] with Trac. |
| 36 | |
| 37 | == Installation |
| 38 | |
| 39 | A prerequisite for installation is [http://www.geocities.com/fiolj/bibtexparse.html bibtexparser], of which a modified version is already included in the plugin. |
| 40 | |
| 41 | Run one of the following commands, depending on the Trac version that you run: |
| 42 | {{{ |
| 43 | #!sh |
| 44 | easy_install http://trac-hacks.org/svn/tracbibplugin/0.10/ |
| 45 | easy_install http://trac-hacks.org/svn/tracbibplugin/0.11/ |
| 46 | easy_install http://trac-hacks.org/svn/tracbibplugin/0.12/ |
| 47 | easy_install http://trac-hacks.org/svn/tracbibplugin/1.0/ |
| 48 | }}} |
| 49 | |
| 50 | == News |
| 51 | |
| 52 | * The new default citation style is an IEEE-like style. |
| 53 | * !BibTeX files can be loaded from external websites. |
| 54 | * Extensionpoint ''IBibRefFormatter'' for custom citation styles introduced. |
| 55 | * Extensionpoint ''IBibSourceProvider'' for custom !BibTeX loaders introduced. |
| 56 | * Wiki pages can be used as bibliograpy. The Entries must be inside a code block. |
| 57 | * The attachments can now be loaded fom any page in the wiki. |
| 58 | * A special page "!BibTex" will be loaded automatically if this page exists, like in [http://trac.edgewall.org/wiki/BadContent BadContent]. |
| 59 | |
| 60 | == Usage |
| 61 | |
| 62 | === Configuration Settings |
| 63 | |
| 64 | You can add a ''''''bibtext'''''' config section in `trac.ini`. In this section you can change the heading of the References and you can add other sources that should always be loaded: |
| 65 | {{{ |
| 66 | #!ini |
| 67 | [bibtex] |
| 68 | heading= Literatur # default: References |
| 69 | auto= source:mybib.bib, wiki:BibTexBlub # default: wiki:BibTex |
| 70 | }}} |
| 71 | |
| 72 | === Load Bibtex Entries |
| 73 | |
| 74 | The way to invoke a bibtex file has substantially changed: |
| 75 | {{{ |
| 76 | [[BibAdd(source:path/to/file[@rev])]] # add a file from source |
| 77 | [[BibAdd(attachment:[wikipage/]file)]] # add a file from a wiki attachment |
| 78 | [[BibAdd(wiki:page)]] # use a wiki page |
| 79 | [[BibAdd(http://www.external.page.com)]] # use a bibtex file from everywhere |
| 80 | }}} |
| 81 | |
| 82 | ==== Examples |
| 83 | |
| 84 | {{{ |
| 85 | [[BibAdd(source:bib.bib@2)]] |
| 86 | [[BibAdd(source:trunk/bib.bib@latest)]] |
| 87 | [[BibAdd(source:bib.bib)]] |
| 88 | [[BibAdd(attachment:fiol.bib)]] |
| 89 | [[BibAdd(attachment:test/lala.bib)]] |
| 90 | [[BibAdd(http://www.external.page.com/bibtex.bib)]] |
| 91 | }}} |
| 92 | |
| 93 | === Cite an article |
| 94 | |
| 95 | ==== Macros |
| 96 | |
| 97 | {{{ |
| 98 | [[BibCite(key)]] |
| 99 | [[BibCite(key,page)]] |
| 100 | }}} |
| 101 | |
| 102 | ==== Wiki Syntax |
| 103 | |
| 104 | {{{ |
| 105 | cite:key |
| 106 | cite:key:page |
| 107 | }}} |
| 108 | |
| 109 | === Add an article without citation |
| 110 | |
| 111 | {{{ |
| 112 | [[BibNoCite(key)]] |
| 113 | }}} |
| 114 | |
| 115 | === Inserting the bibliography |
| 116 | |
| 117 | This renders all cited entries: |
| 118 | {{{ |
| 119 | [[BibRef]] |
| 120 | }}} |
| 121 | |
| 122 | This renders all loaded entries: |
| 123 | {{{ |
| 124 | [[BibFullRef]] |
| 125 | }}} |
| 126 | |
| 127 | If you also want to render all entries from the special page ''!BibTex'', you can write: |
| 128 | {{{ |
| 129 | [[BibFullRef(auto=true)]] |
| 130 | }}} |
| 131 | |
| 132 | === URL/DOI Fields |
| 133 | |
| 134 | ''''''url'''''' and ''''''doi'''''' fields in !BibTex files will be rendered to links if possible. |
| 135 | |
| 136 | === Full Example |
| 137 | |
| 138 | {{{ |
| 139 | = Welcome = |
| 140 | |
| 141 | [[BibAdd(source:mybib.bib)]] |
| 142 | |
| 143 | I am citing here [[BibCite(small)]] and someone said "hello world" [[BibCite(wiki,123)]] and |
| 144 | cite:small:123-124 is important. finally the BibTex entry with the key ''big'' is not cited but |
| 145 | will appear in the references because of tho ''!BibNoCite'' macro. |
| 146 | |
| 147 | [[BibNoCite(big)]] |
| 148 | [[BibRef()]] |
| 149 | }}} |
| 150 | |
| 151 | When rendered this looks as follows: |
| 152 | |
| 153 | [[Image(tracbib2.png)]] |
| 154 | |
| 155 | == Related |
| 156 | * Ticket [ticket:453] |
| 157 | * Ticket [ticket:5175] |
| 158 | * [wiki:CiteMacro CiteMacro] |
| 159 | |
| 160 | == Recent Changes |
| 161 | |
| 162 | [[ChangeLog(tracbibplugin, 3)]] |
| 163 | |
| 164 | == Author/Contributors |
| 165 | |
| 166 | ''''''Author:'''''' [wiki:Amfortas] [[BR]] |
| 167 | ''''''Maintainer:'''''' [[Maintainer]] [[BR]] |
| 168 | ''''''Contributors:'''''' abeld |