diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/biblio/readme.1st |
Initial commit
Diffstat (limited to 'support/biblio/readme.1st')
-rw-r--r-- | support/biblio/readme.1st | 918 |
1 files changed, 918 insertions, 0 deletions
diff --git a/support/biblio/readme.1st b/support/biblio/readme.1st new file mode 100644 index 0000000000..187801da12 --- /dev/null +++ b/support/biblio/readme.1st @@ -0,0 +1,918 @@ + + BIBLIO + bibliographic preprocessor + + + 09 April 2001 + 27 June 2001 + 07 Sept 2001 (ver 1.1) + 17 Sep 2001 (ver 1.11) + 04 Oct 2001 (ver 1.2) + 12 March 2002 (ver 1.21) + +CONTENT + +Abstract + +0. Copyright +1. Statement of Purpose +2. General Ideas +3. Structure of the Biblio-Database +4. Structure of the Format File (Format Strings) +5. Running Biblio +6. Examples +7. Additional Scripts +8. Installation Guide and Short Instruction +9. Perl To C +10. To Do +11. Known Bugs + +=============================================================================== + + Abstract + +Biblio is a programm for preprocessing your bibliographic references. It is +written in Perl and does not use the LaTeX internal language. After +preprocessing the input TeX file it creates output TeX file with references +included according to the formats prescribed either in a separate file +(called "template" or "format file" further on) +or in the header of the input TeX file. Output TeX is ready for LaTeX. +If you do not need details, move to the section 8 (and 9) of this text. + + +------------------------------------- + +0. COPYRIGHT + +This is free software. But NO use in commercial purposes is allowed. +There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR +PURPOSE. + +------------------------------------- + +1. STATEMENT OF PURPOSE + +Don't reinvent a wheel - this should be your first reaction. Might be you are +right: many people use BibTeX or some other (I don't know which but pretty sure +they do exist) programs to pre-process their bibliographic references lists. +But what I did before was just including all citations directly into my +TeX-file. Before... Before this story has happened. + +I was writing an article and from the very beginning we (I and my bosses) +decided to send it to the Journal A. Of course, I wrote everything including +citations in the style of this journal. But when the work was almost finished +we (you know whom I mean) decided to send the paper to another journal, say +Journal B. And of course it has different rules and standards. +No problem - one should say,- Use BibTeX. Yes, that's OK - is my reply. +But what I basicly needed was to change the order of names (last, first, etc) +in the authors list. Like instead of "J.J.Smith" now I needed "Smith, J.J.". +Might be information I used was quite outdated, but I could not find the way to +handle this kind of things with the BibTeX. + +Another reason to start this project was handle somehow ordering of the +citation list. Normally articles in the "References and Notes" section should +appear in the same order as they are in the body-text. But sometimes it's quite +useful to have the list ordered according to the first author name or something +different. + +And finally, some journals prefer to have "as raw text as possible". They do +accept TeX-files but... without cross references and citations which means, +that everything have to be done by hands and ONLY ONE file has to be submitted. +I don't like this idea! But I DO want to be published there! So, may be a +partial solution is (for citations at least) is to pre-process the TeX-file to +another TeX-file where all \cite and \bibitem commands are substituted by +normal text. Of course, according to some pattern. This solves one more +problem - I'm not very good in TeX programming and find it quite difficult to +make TeX command \cite produce some nice output in the form $^{1,2,6}$ instead +of [1,2,6]. + +So, let's move to the GENERAL IDEAS + +----------------------------------------------------- + +2.GENERAL IDEAS + + A. This program pre-processes TeX-file making another TeX-file. + + B. Citations are inserted from the DataBase(s) which has form of a separate +file. Fields of the records in this file are absolutely ARBITRARY, except for +LABEL and TYPE. Field AUTHOR has also some special meaning which will be +clarified further on. +This DataBase has form of +====================================================== +LABEL = Landau +TYPE = book +AUTHORL = Landau|Lifshits +AUTHORF = L |E. +AUTHORM = D. |M. +TITLE = Statistical Physics +PUBL = Pergamon +PLACE = Oxford +YEAR = 1980 +---------- +LABEL = Vasilevskaya +TYPE = article0 +AUTHORL = Vasilevskaya|Klochkov|Khalatur|Khokhlov|Brinke +AUTHORF = V. |A. |P. |A. |G. +AUTHORM = V. |A. |G. |R. | +TITLE = Microphase separation within comb-like copolymer with attractive side-chains: computer simulations. +JOURNAL = Macromol. Theory and Simul. +STATE = accepted +---------- +LABEL = Helfand1 +TYPE = article +AUTHORL = Helfand|Wasserman +AUTHORF = E. |Z. +AUTHORM = |R. +JOURNAL = Macromolecules +VOL = 9 +PAGE = 879 +YEAR = 1976 +---------- +LABEL = 3dFlex +TYPE = article +AUTHORP = | | |ten +AUTHORL = Subbotin|Saariaho|Ikkala|Brinke +AUTHORF = A. |M. |O. |G. +TITLE = Elasticity of comb copolymer cylindrical brushes +JOURNAL = Macromolecules +PAGE = 3447 +YEAR = 2000 +VOL = 33 +---------- +LABEL = Dobrynin1 +TYPE = article +AUTHORL = Dobrynin|Erukhimovich +AUTHORF = A.|I. +AUTHORM = V.|Y. +TITLE = Computer-aided comparative investigation of architecture influence of block copolymer phase diagrams +JOURNAL = Macromolecules +PAGE = 276 +EPAGE = 281 +YEAR = 1993 +VOL = 26 +COMMENT = Read it before you have graduated!!! +---------- +==================================================================== + +Please, note that the last entry has EPAGE (which means "end page") and title +also included whereas record "Helfand1" contains much less information. +This will not cause any problem. The only person to whom you have to agree is +yourself: if you call the first (starting) page of the paper (book, etc) "PAGE", +do it for all entries. If you prefer to call it "EGAP" - it's your choice! + +One can use abbreviation in the form of TeX commands, like +"\mml" can mean "Macromol." if we include line "\def\mml{Macromol.}" +somewhere in the tex-source. To do so see "-a" option: to point to the +abbreviations file "-a abbr.tex" should be used. Note: Biblio will not check +consistency of your abbreviations!!! + +LABEL and TYPE are predefined! Also AUTHOR is predefined. "AUTHOR" without "L", +"R" or anything else at the end. It is predefined in the sense, that entries in +the database, which start with "AUTHOR" ("AUTHORL", "AUTHORF") are considered to +be arrays with separator "|". There are two equivalent ways to represent them +in the DataBase: +* one is shown above (with "|" as separator) +* the "Dobrynin1" entry can be also written in the form +============== +AUTHORL = Dobrynin +AUTHORF = A. +AUTHORM = V. +AUTHORL = Erukhimovich +AUTHORF = I. +AUTHORM = Y. +=============== +The only important issue is the order of this entries: the first AUTHORF belongs +to the first AUTHORL. In principle you can include anything between them, like: +=============== +AUTHORL = Dobrynin +YEAR = 1993 +AUTHORF = A. +AUTHORM = V. +PAGE = 276 +AUTHORL = Erukhimovich +AUTHORF = I. +AUTHORM = Y. +============== +It will produce the same result. + +If there are several entries for the same key (like YEAR) which is NOT supposed +to be array (i.e. does not start with AUTHOR), then only the last one will +influence the final result. + +The fact that all arrays should start with AUTHOR does not mean that you can +apply it to the authors' list only. It will become more transparent further. + + C. Of course you want some nice output. Your LaTeX document should look like: + +==== +\documentstyle[12pt,a4]{article} +\title{Blah-blah} +\begin{document}\maketitle + +Text text \cite{Dobrynin1}. +Text Text text \cite {Dobrynin1,3dFlex} + +\begin{thebibliography} + +\end{thebibliography} + +Something more you need (list of figures or whatever) + +\end{document} +==== + +Note, that NOTHING is between \begin{thebibliography} and +\end{thebibliography}. These two are just signs for Biblio to insert your +references list in between. + +What does Biblio do? It reads your TeX-file and finds all references (which you +have in \cite command) in the database. Then it inserts them according to some +formats (see further) between \begin{thebibliography} and \end{thebibliography}. +It can do it in two ways: + +FIRST: insert them as "\bibitem{LABEL} TEXT OF THE REF" and not touching +anything else (text of the ref is according to the format, of course); + +SECOND: insert them in some special way, where you can define what \cite will +produce and what kind of numbering you want in the references list. For example, +if you like $^{1,5-7}$ more than standard [1,5-7], normally produced by \cite, +and +(1) ref1 +(2) ref2 +instead of +[1] ref1 +[2] ref2 +produced by \bibitem. + +(Hint: your choice between FIRST and SECOND you can do by using "--nobibitem" +parameter, and "cite_format" and "ref_format" fields in the format file). + +After it's done, you can process output file with normal LaTeX. + +(Hint: You can find script "libtex" which will help you to handle it.) + + D. All formats are stored in the format file (see -f command line option) +or just in your TeX document's header. About rules (how to write this formats) +you can read below. + + + E. So, your checklist is: + 1. Input TeX file. + 2. References database. + 3. Format file + +If you have all these you have to do + +biblio -o outdoc.tex -d refsdata.db refsdata1.db -f formats.db indoc.tex + +where +- outdoc.tex - output filename + (if not given, them "biblio."-prefix is added to "indoc.tex" + like "biblio.indoc.tex") +- refsdata.db - references database (may be more than one) +- formats.db - format file (only ONE) +- indoc.tex - input file + +The order of the parameters is not important. + +------------------------------------- + +3. STRUCTURE OF THE BIBLIO-DATABASE + +It has form described in 2.B. It consists of records. After each record a +separator has to be placed. By default, it is "----------\n". You can easily +change it by command line option "--separator". Only on separator can be used! + +Each record has fields. One line per one field - is a rule! +You cannot change it (without looking into the source, of course)! + +Each field has a structure NAME = VALUE. + +Fields' names LABEL and TYPE are predefined - each record has to have them. +Otherwise it will be ignored. + +Field AUTHOR has a special structure. +Usage is quite obvious from an example + +AUTHORP = | | |ten +AUTHORL = Subbotin|Saariaho|Ikkala|Brinke +AUTHORF = A. |M. |O. |G. +AUTHORM = V. + +There are 4 authors: Subbotin A.V.; Saariaho M.; Ikkala O. and ten Brinke G. + +P, L, F and M are from "prefix", "last", "first", "middle". + +Sign "|" separates authors. It is reserved and cannot be changed! + +You can use as many fields as you like. If you don't use them in the +output - no problem, part of them will be ignored. + +You can have several databases. Use inline option "-d" to say Biblio names +of databases you want to use. + +That's all! + +------------------------------------- + +4. STRUCTURE OF THE FORMAT FILE (FORMAT STRING) + +Your output (formated entries from database put into the TeX document) has to +be formated according to the rules described in the so called format file (or +templates) or just in the beginning of your TeX document. +The first way is preferable - it gives taste of more structural ordering. +Use option "-f" to point to a format file. Otherwise Biblio will try to find +formats in the TeX-file and, if not succeeded, will complain and halt. + +What we want to format? +1. References list (what you normally have at the end of your paper) +2. Citations in the text (what you do with \cite) + +Before reading this, read 2.C from "General Ideas" section. + +How to write formats? That's the hardest part! + +Let's start from an +EXAMPLE: +------------------- +% this is template for Macromolecules +% no ordering of the references is needed. Otherwise add line +% '%ordering= AUTHORL' - ordering with key field 'AUTHORL' + +%begin{biblio} + +%cite_format={(%s)} +%ref_format=${^{%s}}$ + +%% normal article: +% ARTICLE [$AUTHOR0P~L,~F~M; $ {\it $JOURNAL$} {\bf $YEAR$}, {\it $VOL$}, $PAGE$.] + +%% article which is submitted or accepted +% ARTICLE0[$AUTHOR0P~L,~F~M; $ {\it $JOURNAL$} $STATE$.] + +%% normal book +% BOOK [$AUTHOR0P~L,~F~M; $ {\it $TITLE$}; $PUBL$: $PLACE$, $YEAR$.] + +%% article in a book AUTHORE, AUTHORG and AUTHORH - last, first +%% and middle names of the editor +% EDBOOK [$AUTHOR0P~L,~F~M; $ in {\it $BOOKTITLE$}, edited by $AUTHOR0I~E,~G~H;$; $PUBL$: $PLACE$, $YEAR$.] + +%% article in a book without editor +% INBOOK [$AUTHOR0P~L,~F~M; $ in {\it $BOOKTITLE$}, p.$PAGE$ $PUBL$: $PLACE$, $ +YEAR$.] + +% EPRINT [$AUTHOR0P~L,~F~M; $ in {\it $BOOKTITLE$} $INFO$, $YEAR$.] + +%end{biblio} +------------------- +4.0. Syntax + + A. Each line starts with %-sign. This is needed because in principle this can + be included into your TeX-document, so it has to be considered as a comment + by LaTeX. Lines, starting with %% are "REAL" comments (i.e. they are + comments for Biblio too). + + B. All this information has to be stored either in a template file (format + file) [use option -f filename] or just in the header of your TeX document. + In both cases it has to start with '%begin{biblio}' line and end with + '%end{biblio}'. + Only one template file is allowed (you cannot read from 2 for the + same document). + + C. There are some OPTIONAL reserved keys. If omitted, default values are + assumed and warning is printed. + Reserved keys are + C.1. cite_format: has a form %cite_format={(%s)} + %s just means "string". {(%s)} will produce output in your + references list like + + (1) Simpson,.... + (2) Tompson... + ... + + or %cite_format={%s.} will produce + + 1. Simpson,.... + 2. Tompson... + ... + + + C.2. ref_format: has a form %ref_format=${^{%s}}$ + This means how your \cite command output will look like. + For example, we have \cite{Aw1,Paper3,John} in the TeX document and + %ref_format=${^{%s}}$ in your format file. Then you get + + ${^{2,4,5}}$ (numbers depend on what is ordering, of + course) + or + ${^{2-4}}$ if they all are going one by one in your refslist. + + in the output TeX file instead of your \cite command. + If you have %ref_format={[%s]} then + + {[2,4,5]} + or + {[2-4]} + + C.3. ordering: has a form %ordering= AUTHORL + This means that the field AUTHORL has to be considered as a key field + in ordering of your references. You can put whatever you want there, + like YEAR, VOL,... + If this filed is not present in some entries, it considered to be + empty. + + D. Each TYPE (TYPE is article, book or something like this) has to have an + entry in the format file. This entry (format string) has a form + + % TYPE [format string] + + (it MUST be in ONE line!!!) + where the "format string" says to Biblio how to output information about + your reference of the type TYPE. + "[" and "]" MUST be there! They say where you start your format line and + where it ends (if you need to use inside the format line, don't worry: + the first [ is the start and the last ] is the end of the string; + all the rest are just characters). + Everything between $-signs is a filed name. $VOL$ will be substituted by + 54 if you have an entry + VOL = 54 + for this given article in your database. + It's a bit more tricky for AUTHOR (see below). + All the other words are just normal text or LaTeX commands. + Example: + + Let say, you have the following item in your database file + + LABEL = LifshitzGrosbergKhokhlov1 + TYPE = article + AUTHORL = Lifshitz|Grosberg|Khokhlov + AUTHORF = I. |A. |A. + AUTHORM = M. |Yu. |R. + JOURNAL = Rev. Mod. Phys. + VOL = 50 + PAGE = 683 + EPAGE = 713 + YEAR = 1978 + TITLE = Some problems of the statistical physics of... + + and an entry + + % ARTICLE [$AUTHOR0P~L,~F~M; $ {\it $JOURNAL$} {\bf $YEAR$}, {\it $VOL$}, $PAGE$.] + + in your format file (I assume also '%cite_format={(%s)}'). + Then output will be + + (1) ~Lifshitz,~I.~M.; ~Grosberg,~A.~Yu.; ~Khokhlov,~A.~R. + {\it {Rev. Mod. Phys.}} {\bf {1978}}, {\it {50}}, {683}. + + +4.1. AUTHOR-word: + + A. Word AUTHOR is reserved and assumed to be an array. + This means, that AUTHORLFM is in fact + hash index with keys AUTHORL, AUTHORF, AUTHORM, + or, if you like + AUTHOR[L]='Smith' + AUTHOR[F]='J.' + AUTHOR[M]='A.' + + B. After the word AUTHOR follows the max number of authors to show + (let us call it max_A). + If actual number of authors n_A > max_A, + then "$reservedET_AL" will be written after the + author number max_A and names of all the others will be omitted. + "max_A==0" (zero) means "max_A==infty" + C. $AUTHOR0L, F; $ means that fields should be written as follows: + 1) "AUTHORL" + 2) ", " + 3) "AUTHORF" + 4) "; " (let us denote it as "last_sep") + 5) go to "1)" for the next author + + + For example, for the Lifshitz' article above: + + $AUTHOR0L, F, M; $ produces + Lifshitz, I. M.; Grosberg, A. Yu.; Khokhlov, A. R. + + or + + $AUTHOR1L, F; $ produces + Lifshitz, I. et al + + Note, there is no the middle name in the 2nd example, because there is + no "M" in the format line. + + D. There is a special sign "|" which means that AUTHOR format line is ended + in fact and everything after it is so called "and_word". + This "and_word" (normally, it contains only "and") is something what is + written before the last author if the number of authors in larger than 1. + + Example: + $AUTHOR0L, F, M; |and$ produces + Lifshitz, I. M.; Grosberg, A. Yu.; and Khokhlov, A. R. + + + Note, that + 1) if "et al" have to be printed, "and_word" will not be there! + + $AUTHOR2L, F; |and$ produces + Lifshitz, I.; Grosberg, A. Yu. et al + + 2) if number of authors is larger than 2 but less or equal to max_A: + before the "end_word" the "last_sep" has to be written + otherwise - if only 2 authors: print "and_word", but no "last_sep" + + Example: Q.W. Rom and R.T. Lai + but Q.W. Rom, T.G. Doi, and R.T. Lai + here: last_sep="," ; and_word="and") + + This example corresponds to + $AUTHOR0FM L, |and$ + + +4.2. Fields LABEL, TYPE and AUTHOR are predefined. All the others can be named + by you. The only condition is: your fields in the database and in the formats + have to coincide. If some field is present in the format string but there + is no value of it in the database, sign $reservedEMPTY_FIELD_SIGN will be + printed out instead (see command line parameter --empty_field_sign); + by default $reservedEMPTY_FIELD_SIGN == '???'. + My suggestion is: use YEAR, VOL, PAGE, etc. for the year, volume and page and + don't name page as RTY45 - this is mush less readable. + +------------------------------------- + +5. RUNNING BIBLIO + +So, now you have references database and format file. It is time to talk about +command line parameters. Here they are: + + ESSENTIAL PARAMETERS + ++ -o output.file => $OUT_TEX ; + if no given, assuming $OUT_TEX = "biblio.$TEX_NAME" ++ -f format.file => $FORMAT_NAME + (can introduce templates for Macromolecules, + etc. If given, "in-tex" parameters will be + ignored!!!) + ++ -d dbase.file => @REFS_FILES (where all info about refs is!) + accepts many arguments + ++ -a abbrev.file => file of abbreviations (tex file) + if given, will be inserted just BEFORE + "\begin{references}" in the output.file. + Consists of anything you want, but the idea is + to use it like "\def\mml{Macromol.}" + and have entry + JOURNAL = \mml + instead of + JOURNAL = Macromol. + in the dbase.file. + ++ -v <number> => verbosity level (0-5) $verbosity_level + ++ -h or --help => short help information + ++ --nobibitem => $optionsKEEP_BIBITEM_AND_CITE=0. Default is 1!!! + (read 2.C too) + If not given, Biblio will insert all references +(formated, of course) into the out-TeX document, and that's it! You will +have \cite-commands as you had them before. List of references will be +produced by LaTeX itself (with \bibitem). +If given (but NO --uselist), it will print your references as a simple text, +flushed left. + + ++ --uselist => $optionsREFS_AS_TEX_LIST=1 Default is 0!!! + Will output the references list as a TeX list +with counter. Looks much better than \flushleft (try it!) + + +(if no --nobibitem nor --uselist is given it is assumed to use \bibitem + if --nobibitem is given, it will use \flushleft + if --nobibitem AND --uselist are given it will use \list +) + + + ADDITIONAL PARAMETERS + + key variable in the source,default value + and some info + ++ --etal "{\it{et al}}" => form of "et al"-string in $reservedET_AL + (see 4.1.C) ++ --separator "----------\n" => separator in the database-file + ++ --not_insert_empty_field_sign => $optionsINSERT_EMPTY_FIELDS_SIGN=0 + If some field is present in the format +string for the given TYPE, but is not in the database, Biblio will +insert some sign instead (see --empty_field_sign). + ++ --empty_field_sign xxx => $reservedEMTY_FIELD_SIGN = '???' + (see --not_insert_empty_field_sign) + ++ --start_refs => @STARTREFS= + accepts many arguments ('begin{references}','begin{thebibliography}'); + Tells where Biblio has to start inserting + the references list. + ++ --end_refs => my @ENDREFS= .... + accepts many arguments + +? --bibitem_string => my $BIBITEM = '%'."\n".'\bibitem{'; + ++ --version => version info + ++ --movepoint => added in ver1.1 + make "word.\cite{} Another sent" + from "word \cite{}. Another sent" + Everything in the variable $what_we_call_point='.,;:' is considered + to be a "point". + This way of making citations is required by some journals + (for instance, Macromolecules) which have citation in the form + "in recent works$^1-5$" + There point (or comma,...) has to be placed BEFORE citation, like + 'works.$^{1-5}$' but NOT 'works$^{1-5}$.' + NOTE: this will work only for point IN THE SAME LINE, like + 'was show recently \cite{q2,lab4,yt6}. Therefore' + but NOT for + 'was show recently \cite{q2,lab4,yt6} + . Therefore' + +(not everything is accomplished. So, ?-sign means, that in your version +this parameter might be still not working) + +------------------------------------- + +6. EXAMPLES + + A. I have a couple of format files (in the directory called "formats") +and a database. First, about the structure, I decided to follow. (It does +NOT mean you have to do it in the same way!) + +Types I use are + +ARTICLE just regular article +ARTICLE0 submitted or accepted article + +BOOK regular book +EDBOOK article in a book (with an editor!) +INBOOK article in a book without editor + +EPRINT electronic preprint + +Some examples of format files you can find in the "formats" directory. + +Example of a database is called "refers.db". + + + B. Document "EXAMPLES/2sorts/2sorts.tex" is an introduction +to one of my articles. You can use it as an example. +It needs templates which are in the "formats" dir. +Just type "./libtex" and that's it! + + C. Document "EXAMPLES/2sorts/2sorts_formats.tex" is +the same as in B., but all formats are included into the header +of the document. Read this header to find out how to compile it. + + D. Document "EXAMPLES/hairy/hairy.tex" shows how to use abbreviations. + +------------------------------------- + +7. ADDITIONAL SCRIPTS + +You can find some more scripts in the top directory. + + A. libtex + is a useful script for processing TeX documents on the + stage of their development. It can be easily adjusted + (open it in any text editor and change parameters). The idea is + to keep its copy at the same directory where your document (tex file) + is situated. + Then instead of running LaTeX itself you have to run "libtex" as + libtex filename + ("filename" WITHOUT tex extension!!! For 2sorts.tex it is "2sorts") + + JOURNAL - name of the template + PREFIX - Biblio's home directory (where in the "formats" directory all + formats are stored) + + B. biblist_html + Makes an HTML formated list from your references database. I use (as you + could see in refers.db) field URL for articles, which I have + electronically. This script will run "biblist.pl" (see below) with --html + key. This will produce nice html output with hyperlinks to your e-library + (it will put prefix "--prefix" for all hyperlinks except starting already + with "http:" ) + Of course, you can use "--prefix /home/usrname/base/" if you want to make + all refs local. + + C. biblist + The same as the previous one but output in TeX format. Uses biblist.pl + without --html key. + + D. biblist.pl + Makes a list of references from the whole database file. Can output in + TeX file or HTML. Has switches: almost all, which biblio has plus --html. + Does not have --uselist (it is always on), --start_refs, --end_refs. + And, of course, it does not need an input TeX file! Therefore you + always have to provide format file. + If --html is not given, produces TeX file. + HTML output needs special formats, of course. Example is in + EXAMPLES/formats/formats_html.biblist + + Example of a format file for TeX output is in + EXAMPLES/formats/formats.biblist + + E. bibcheck.pl (added 17 Sep 2001) + Checks your database (one ore more files containing references). + Complains if it has: + - records with empty LABEL or TYPE + - several records with the same LABEL + Has specific parameter "--noexit" which means "do not exit if + found a record without a label, just go on". By default it will + halt in this case. + Parameter -e (or --errors) says "after how many errors exit the program" + (default is 5) + For instance: + bibcheck.pl -e 10 -d myrefers.db onemorerefs.db + or + bibcheck.pl --errors 10 -d myrefers.db onemorerefs.db + will process files "myrefers.db" and "onemorerefs.db" but exit if at + some point number of errors will exceed 10. + + +That's all for the moment. + +------------------------------------- + +8. INSTALLATION GUIDE and SHORT INSTRUCTIONS + +I decided to put this section at the very end because now, I hope, you know what +you are installing. + +After unpacking the archive you have: + + * biblio.pl - the main "executable" + * dir formats - format files (template) and + abbreviations file "abbr.tex". Ready for use. + * biblist.pl; biblist.pl; biblist_html; bibcheck.pl + - some additional scripts (see section 7). + * dir EXAMPLES - examples (see section 6). + +and bash script "install" to help you to install. + +1. Edit script "install" First two lines have to point to + * PREFIX to the directory, where you want to install biblio + (formats, examples, etc.). It must NOT exist yet. + + * BINDIR to the binaries directory, where it will put links to biblio and + biblist + + Edit biblio.pl and ADDSCRIPTS/biblist.pl: in the first line it should be + a full path to your Perl!!! + +2. Run "./install". Then change dir to your PREFIX dir and check, that biblio.pl + and everything in the ADDSCRIPT directory is executable. If not, do + + chmod a+x name_of_the_file + + +3. If installation script failed, you can do it yourself. + Just create a directory for biblio. + Copy there everything you found in the current directory (see above). + Then + + ln -s biblio biblio.pl + + Chenge dir to your normal binaries dir and do + + ln -s biblio PREFIX/biblio + ln -s biblist.pl PREFIX/ADDSCRIPT/biblist.pl + + where PREFIX has to be a real path (like /usr/local/biblio) + + Be sure about file permissions (everybody, or at least you, has to be + able to execute!). + +That's all. Now you have commands "biblio" and "biblist" + +About usage of additional scripts. What I normally do is like this: + +1. Copy libtex from ADDSCRIPTS to the directory where my current TeX document +is. + +2. Edit it + + * JOURNAL is the name of the template + * PREFIX is the place where you keep biblio (and all its stuff) + * REFS is your references database + * FORMATS is a place where you keep format files (templates) + * PROJECT is a name of your TeX file WITHOUT extension. + Normally you do for file myarticle.tex + libtex myarticle + and myarticle goes to PROJECT variable. + But you can just put it like + PROJECT=myarticle + in the text of libtex and then type + libtex + only to compile your TeX document. + +3. After running libtex (if everything goes right) you will have + a file named "myarticle.dvi" and "myarticle.1.tex" and some more, which are + not important. + +Working version of libtex (it works even without any installation) is in the +EXAMPLES dir. Try it. +----- + +About biblist - it produces a full references list from all the entries you have +in your database. Copy it somewhere and edit: +REFSTEX is the output file; +FORMATS is the format file. You can edit it, if you like. + +Run biblist and you get references.tex file, and references.dvi file. +----- + +About biblist_html - does the same what biblist does, but outputs in HTML. +About --prefix option you can read in 7.B and 7.C. Formats, of course, are +different from what you use for TeX output. I provide formats_html.biblist file +(find it in the "formats" directory) - you can easily edit it. + +------------------------------------- + +9. PERL TO C + +If everything went OK and you are going to use biblio, I have an idea about +speeding it up. You can use "perlcc" to make a real binary from Perl's script. +Sometimes it is a good idea, sometimes not. What I found: binary of biblio +is 50% (yeah, yeah - 50!) faster than Perl-script. So it is worthy of trying! +Do: + + perlcc -o biblio.exe biblio.pl + +and you will get biblio.exe executable (it will take some time - translation to +C and then compilation). + +If you succeeded, make a link called "biblio" to biblio.exe (at the same +directory, where you have biblio.pl; so, you have to erase an old link biblio +pointing to biblio.pl). + +All the rest is the same. + +If you are interested in C sources, try + + perlcc -sav -o biblio.exe biblio.pl + +It will save sources for you! Just great! Althoug I don't think, this C-source +is really readable! :) + +------------------------------------- + +10. TO DO + +A lot of things are very raw. Only a couple of people tried it and I cannot say +it was sufficiently tested. So if you discover any bug or have any suggestion +write directly to me (rstepanyan@yahoo.com). + +This script now supports only very primitive way of citation: each citation +is numbered and this number is its identifier. So, citation in the form +"Smith(1990a)" are impossible. That is, probably, the first thing to do +(This kind of citations is used in Rev. of Modern Physics, for instance). + +I do not have too much time right now, but I am constantly thinking about it. + +------------------------------------- + +11. Known Bugs + +11.A. Lost Lines (for ver.1.2 only) + +From ver.1.2 there is no points and commas at the beginning of the line. +Like in the piece of text + + Was shown in work + \cite{lab2}. Blah-Blah-Blah + +if we use --movepoint option we get + + Was shown in work + .\cite{lab2} Blah-Blah-Blah + +(and ver.1.1 really did it this way). +But it should be (and from ver.1.2 it IS) + + Was shown in work.\cite{lab2} Blah-Blah-Blah + +That is exactly what is fixed now. Although it adds a new bug: if you have + + Was shown in work + % Blah-Blah-Blah + \cite{lab2}. Blah-Blah-Blah# + +then one line is LOST!!!! (Guess why!) + +------------------------------------- +Oh, now it is really the EOF!
\ No newline at end of file |