Sign on

SAO/NASA ADS -> Help -> ADS Custom Format
SAO/NASA ADS Help Pages Prev |


    6.7 - The ADS Custom Format

    The custom format feature allows you to output ADS data in a completely user-defined format. This allows you for instance to adapt your reference format to the requirements of a specific journal, or to build other types of output like HTML formatted references.

    The format can be specified as a string using a syntax similar to the one used by the C-programming printf statement. The format string is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output; and conversion specifications, for any of the fields found in the bibliographic record to be formatted (e.g. authors, title). The "\" character is used to specify special characters, as in a printf format ("\n" is a newline, "\t" is a tab, "\\" is a backslash). Each conversion specification is introduced by the character "%", and it takes the following form:
        %[s][c][n.m]f[e]
    
    where:

    s: Starting character (optional).
    This character will be printed before the string specified by the format character is printed. If the starting character is one of [ , . ; : ] it will be followed by a space. If it is necessary to include more than one characters as a starting string, the syntax is %\(string)[c][n.m]f[e]. If string needs to contain a ")", it needs to be escaped with a backslash. Using a string as starting value is for instance usefull to output a bold volume like {\bf 23}, . The format for this would be %\({\bf )V\(}, )

    This character is only printed if the field itself is available. This can be any non-alphanumeric character except =, &, /, and \ (the encoding characters). If this field contains a character that is not a valid starting character, it is assumed to be an encoding character.

    c: Encoding (optional).
    This character specifies what encoding scheme to use. Options are:

    &: SGML encoding.
    This encoding converts the characters &, <, >, and " to &amp;, &lt;, &gt;, and &quot;, respectively.

    >: HTML encoding.
    This encoding converts characters in URLs to hex notation, and & to &amp;. Outside URLs, the characters &, <, >, and " are converted to &amp;, &lt;, &gt;, and &quot;, respectively.

    /: URL encoding.
    This encoding converts the characters &, ?, and + to the hex encoded values.

    =: Hex encoding.
    This encoding converts all characters with hex values less than 0x20 and all characters with hex values greater or equal to 0x7F into the form %XX where XX are the two hex digits.

    \: Tex/Latex encoding.
    This encoding converts all special Tex characters into their Tex escape sequences. For instance '\' is converted to '$\backslash $', '$' is converted into '\$', '^' is converted into '\^{}', etc.

    n.m: Maximum number of entries in field (optional).
    This is implemented for the author field. If the number of authors in the list is larger than n, the list will be truncated and returned as "author1, author2, ..., authorm, et al.". If .m is not specified, n.1 is assumed.

    f: Output field specifier.
    This character specifies which field is to be printed with this format specification. The valid field specifiers are described below.

    e: Ending character (optional).: This character will be printed after the string specified by the format character is printed. If the ending character is one of [ , . ; : ], it will be followed by a space. This character is only printed if the field itself is available. This can be any non-alphanumeric character except "%" and "\". If it is necessary to include more than one characters as an ending string, the syntax is %[c][n.m]f\(string). If string needs to contain a ")", it needs to be escaped with a backslash. Otherwise, if a character is in this field that is not a valid ending character, the format ends here and the character is interpreted as a regular format character. A "\" is used if the following character would be a valid ending character but should not be considered part of the format (meaning it should be printed regardless of whether the format is printed). It also prevents the addition of a space after , . ; : .

    6.8 - Output Field Specifiers

    The output field specifiers can be grouped in one of the following categories: the special format characters, author formatting characters, and other characters. All of them are described below.



    Special formats

    z: Extended formats
    Since we were running out of format letters, we added additional formats that start with a z.

    znnn: Line length
    With this you can specify the maximum line length on output. The syntax is %znnn, where nnn is the line length. A line length of 0 means that the output is not broken in multiple lines at all. This format produces no output.

    zn: Enumeration
    This format outputs the sequence number of the record in the output

    Z: Command format
    This is a special format. It must be the first command. There can be mul;tiple %Z formats at the beginning of the format string. It allows you to specify certain commands with parameters. It produces no output. It has the following syntax: %Zcommand:parameter. Parameter can be a number, a word, or a string, depending on the command. If it is a string, it needs to be enclosed in double quotes. The available command are:
    Encoding:word This specifies the encoding of the output. Available encoding parameters are:
    UTF-8: UTF-8 encoding of all unicode characters.
    ISO-8859-1: ISO-8859-1 (Latin-1) encoding of all unicode characters.
    ISO-8859-2: ISO-8859-2 (Latin-2) encoding of all unicode characters.
    TeX: TeX encoding of all unicode characters.
    hex: Hex encoding of all unicode characters.
    Unicode: Unicode encoding of all unicode characters. This outputs the html entities instead of binary characters.
    Linelength:number This specifies the linelength for the output (like %z).
    Header:"string" This specifies a header that will be output once before the data records.
    Footer:"string" This specifies a footer that will be output once after all the data records are output.
    EOL:"string" This specifies the character to be printed at the end of a record (newline by default)

    Author formats

    A: Authors
    This field prints out the author list as it is in the database. If the maximum number of entries in the field is specified, the output will be truncated to first author, et al. if there are more than n authors. The last author is separated by 'and'.

    a: Authors
    This field prints out the author list as it is in the database. If the maximum number of entries in the field is specified, the output will be truncated to first author, et al. if there are more than n authors. The last author is separated by '&'.

    G: Authors (last names first)
    This field prints out the author list. The author first names are truncated to first initials. The authors are written as 'lastname f. i.' (no comma separator for f. i.). If the maximum number of entries in the field is specified, the output will be truncated to author1 f. i., author2 f. i., author3 f. i., et al. if there are more than n authors. The last author has no special separator.

    g: Authors (last names first)
    This field prints out the author list. The author first names are truncated to first initials. The authors are written as 'lastname f. i.' (no comma separator for f. i.). If the maximum number of entries in the field is specified, the output will be truncated to author1 f. i., et al. if there are more than n authors. The last author has no special separator.

    H: Reference Name
    This field prints out the reference author name if available. It consists of either "Lastname" (for one-author articles), or "Lastname1 and Lastname2" (for 2 author articles), "Lastname1 Lastname2 and Lastname3" (for 3 to n-1 author articles), or "Lastname1" (for articles with more than n authors). Default for n is 3. It can be changed for instance to 1 with %1H.

    h: Reference Name
    This field prints out the reference author name if available. It consists of either "Lastname" (for one-author articles), or "Lastname1 & Lastname2" (for 2 author articles), "Lastname1 Lastname2 & Lastname3" (for 3 to n-1 author articles), or "Lastname1" (for articles with more than n authors). Default for n is 3. It can be changed for instance to 1 with %1h.

    I: Authors (initials first)
    This field prints out the author list. The author first names are truncated to first initials. The first author is written as 'lastname, f. i.', subsequent authors are written as 'f. i. lastname'. If the maximum number of entries in the field is specified, the output will be truncated to "first author, and xx colleagues" if there are more than n authors. The last author is separated by 'and'.

    i: Authors (initials first)
    This field prints out the author list. The author first names are truncated to first initials. The first author is written as 'lastname, f. i.', subsequent authors are written as 'f. i. lastname'. If the maximum number of entries in the field is specified, the output will be truncated to first author, et al. if there are more than n authors. The last author is separated by '&'.

    L: Authors (last names first)
    This field prints out the author list. The author first names are truncated to first initials. The authors are written as 'lastname, f. i.'. If the maximum number of entries in the field is specified, the output will be truncated to "first author, and xx colleagues" if there are more than n authors. The last author is separated by 'and'.

    N: Authors (last names first)
    Same as L, except the last author is is not treated differently form the others.

    l: Authors (last names first)
    This field prints out the author list. The author first names are truncated to first initials. The authors are written as 'lastname, f. i.'. If the maximum number of entries in the field is specified, the output will be truncated to first author, et al. if there are more than n authors. The last author is separated by '&'.

    M: Author list (last names only)
    This field prints out the last names of the authors if available. The reference name is the citation that is used in the article text. It consists of either "Lastname" (for one-author articles), or "Lastname1 and Lastname2" (for 2 author articles), "Lastname1, Lastname2 and Lastname3" (for 3 to n-1 author articles), or "Lastname1 et al." (for articles with more than n authors). Default for n is 0, meaning no truncation. It can be changed for instance to 5 with %5M.

    m: Author list (last names only)
    Same as M, except it uses '&' before the last author instead of 'and'.

    n: Author list (last names only)
    This field prints the last name of the first author. If there is more than one author, it appends a '+'.

    za1: Author last name only
    This format prints the last name of the first author.

    za2: Authors (last names first) : Like L, but no space between initials.

    za3: Authors (last names only) : Like M with \emph around et al

    Other formats

    B: Abstract
    This field prints out the abstract if it is available.

    b: Abstract
    Same as B.

    C: Copyright
    This field prints out the copyright statement if available.

    c: Citation count
    This outputs the number of citations to the article.

    D: Publication Date
    This field prints out the Publication date if available.

    d: DOI
    The Digital Object Identifier of the article if available.

    E: Electronic Data Table Address
    This field prints out the electronic data table address if available.

    e: Electronic Data Table Address
    Same as E.

    F: Author Affiliation
    This field prints out the Author affiliation if available.

    f: Author Affiliation
    Same as F.

    J: Journal
    This field prints out the journal name.

    j: Journal
    This field prints out the journal name if available. If an AASTeX macro for the journal is available, this macro is printed instead.

    Q: Journal
    This field prints out the full journal information if available.

    q: Journal
    This field prints out the journal abbreviation.

    K: Keywords
    This field prints out the keywords if available.

    k: Keywords
    Same as K.

    O: Object Names
    This field prints out the object names if available.

    o: Object Names
    Same as O.

    P: Last Page
    This field prints out the last page number of the article if available.

    p: First Page
    This field prints out the first page number of the article if available.

    R: Bibliographic Code
    This field prints out the bibliographic code if available.

    r: Bibliographic Code
    Same as R.

    S: Reference Source
    This field prints out the reference source if available.

    s: Reference Source
    Same as S.

    T: Title
    This field prints out the title if available.

    t: Title
    Same as T.

    U: URL
    This field prints out the URL of the abstract as a complete hyperlink with the bibcode as the anchor in the form: <a href="url">bibcode</a>

    u: URL
    This field prints out the URL of the abstract in the form: http://adsabs.harvard.edu/abs/bibcode

    V: Volume
    This field prints out the volume if available.

    v: Volume
    Same as V.

    W: Publication Category
    This field prints the publication category. Currently available categories are:

                 MISC
                 BOOK
                 INBOOK
                 PROCEEDINGS
                 INPROCEEDINGS
                 ARTICLE
                 PHDTHESIS
                 MASTERSTHESIS
                 TECHREPORT
    
    
    w: Publication Category
    Same as W.

    X: arXiv e-print number
    This fields prints the identifier corresponding to the paper's e-print, as assigned by the arXiv.

    x: Comments
    This field prints any of the comments available for the record.

    Y: Publication Year
    This field prints out the publication year if available.

    y: Publication Year
    Same as Y.



    Examples:

    The default format is the AASTeX format:
        \\bibitem[%\4m%(y)]%{R} %\8l %\Y,%\j,%\V,%\p\n
    
    
    This format produces a reference of the form:
        \bibitem[Rester et al.(1989)]{1989ApJ...342L..71R} Rester, A.~C.,
              Coldwell, R.~L., Dunnam, F.~E., Eichhorn, G., Trombka, J.~I.,
              Starr, R., \& Lasche, G.~P.\ 1989, \apjl, 342, L71 
    
    
    The format for Icarus is:
        \\bibitem[%\2M%(y)]%{R} %\10I %\Y.%\t.%\j %\V,%\p%-\P\.\n
    
    
    The format for MNRAS is:
        \\bibitem[\\protect\\citename%{\1h} %y]%{R} %\8.3g,%\Y,%\q, %\V,%\p\n
    
    
    The reason for including the starting and ending character within the format specification is to handle cases where the output field is not available. For instance to print the year followed by the comment in parenthesis you can specify:
        %Y (%x)
    
    or
        %Y %(x)
    
    If there is no comment field available, the first format will print:
        1998 ()
    
    whereas the second format will print:
        1998
    
    


Top |