001// BiblioDescription.java
002//
003//    senger@ebi.ac.uk
004//    March 2001
005//
006
007/*
008 *                    BioJava development code
009 *
010 * This code may be freely distributed and modified under the
011 * terms of the GNU Lesser General Public Licence.  This should
012 * be distributed with the code.  If you do not have a copy,
013 * see:
014 *
015 *      http://www.gnu.org/copyleft/lesser.html
016 *
017 * Copyright for this code is held jointly by the individual
018 * authors.  These should be listed in @author doc comments.
019 *
020 * For more information on the BioJava project and its aims,
021 * or to join the biojava-l mailing list, visit the home page
022 * at:
023 *
024 *      http://www.biojava.org/
025 *
026 */
027package org.biojava.bibliography;
028
029/**
030 * <p>
031 * It represents an account of the content of the cited resource.
032 * It is either an abstract, or table of contents, or both.
033 * It can be written in a language different from the language of the cited resource.
034 * </p>
035 *
036 * <p>
037 * Both abstract and table of contents can contain more than just a plain text,
038 * typically they may be expressed in a <em>markup language</em>.
039 * Their formats are defined according to the
040 * <a href="http://www.ietf.org/rfc/rfc2045.txt">MIME</a> specification.
041 * </p>
042 *
043 * @author <A HREF="mailto:senger@ebi.ac.uk">Martin Senger</A>
044 * @version $Id$
045 * @since 1.3
046 */
047
048public class BiblioDescription {
049
050    /**
051     * <p>
052     * It is an abstract of the cited resource. It can be expressed as a plain text
053     * or in a <em>markup language</em>.
054     * </p>
055     *
056     * @see #abstractType
057     */
058    public String theAbstract;
059
060    /**
061     * <p>
062     * It specifies how {@link #theAbstract} is coded.
063     * </p>
064     *
065     * <p>
066     * If it is empty then {@link #theAbstract} is coded as a plain text, using <tt>us-ascii</tt>
067     * coding.
068     * Otherwise, this attribute is equivalent to the  <em>Content-Type Header Field</em>
069     * of the <a href="http://www.ietf.org/rfc/rfc2045.txt">MIME</a> specification,
070     * with exclusion of the keyword <tt>Content-Type</tt>.
071     * For example, it can contain <tt>text/html</tt>, or, using additional parameters,
072     * <tt>text/plain; charset=us-ascii</tt>.
073     * </p>
074     *
075     * <p>
076     * Often abstracts are also available from the same or separate repository as URLs.
077     * There are several ways to provide this information in the here described data model.
078     * The implementations may choose their own way and still remain compliant with this
079     * specification. However, the first approach, described below, is recommended to achieve
080     * interoperability between implementations.
081     * </p>
082     *
083     * <p>
084     * <ul>
085     *   <li> Use here <tt>text/url</tt>
086     *        and put the URL into {@link #theAbstract} field.
087     *   <li> Use here <tt>text/plain; url=xxxxx</tt>
088     *        where xxxxx is a URL of the abstract
089     *        (in this case {@link #theAbstract} may still have a full or partial text of the
090     *        abstract as a plain text).
091     *   <li> Use here a <em>multi-part</em>
092     *        (see <a href="http://www.ietf.org/rfc/rfc2045.txt">MIME</a> specification).
093     *        In such case {@link #theAbstract} will have both the full or partial abstract text,
094     *        and a URL.
095     *   <li> Put the URL into {@link BibRef#properties} using key <tt>abstractURL</tt>.
096     * </ul>
097     * </p>
098     */
099    public String abstractType;
100
101    /**
102     * <p>
103     * It is a table of contents of the cited resource.
104     * It can be expressed as a plain text or in a <em>markup language</em>.
105     * </p>
106     *
107     * @see #tableOfContentsType
108     */
109    public String tableOfContents;
110
111    /**
112     * <p>
113     * It specifies how {@link #tableOfContents} is coded.
114     * </p>
115     *
116     * <p>
117     * If it is empty then {@link #tableOfContents} is coded as a plain text, using <tt>us-ascii</tt>
118     * coding.
119     * Otherwise, this attribute is equivalent to the  <em>Content-Type Header Field</em>
120     * of the <a href="http://www.ietf.org/rfc/rfc2045.txt">MIME</a> specification,
121     * with exclusion of the keyword <tt>Content-Type</tt>.
122     * </p>
123     *
124     * @see #abstractType abstractType for example
125     */
126    public String tableOfContentsType;
127
128    /**
129     * <p>
130     * It defines a language used for {@link #theAbstract} and {@link #tableOfContents}.
131     * The recommended values are discussed in {@link BibRef#language}.
132     * </p>
133     *
134     * <p>
135     * <em>Note that there is no mechanism how to specify different languages for
136     * the abstract and table of contents for one citation.</em>
137     * </p>
138     */
139    public String language;
140
141}