You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

119 lines
4.0 KiB

4 years ago
////
Included in:
- user-manual: Header
////
The author of a document is listed on the line beneath the document's title.
An optional email address or URL can follow an author's name inside angle brackets.
Let's add an author with her email address to the document below.
[source]
----
include::ex-author.adoc[tag=base]
----
.Result: Rendered author and email information displayed on the byline and referenced in the document's body
====
image::author-email.png[Author and email attributes]
====
As you can see in the example above, Asciidoctor uses the author's name and email to assign values to a number of built-in attributes that can be used throughout the document's body.
These attributes include:
`author`::
The author's full name, which includes all of the characters or words prior to a semicolon (`;`), angle bracket (`<`) or the end of the line.
`firstname`::
The first word in the author attribute.
`lastname`::
The last word in the author attribute.
`middlename`::
If a firstname and lastname are present, any remaining words or characters found between these attributes are assigned to the middlename attribute.
`authorinitials`::
The first character of the firstname, middlename, and lastname attributes.
`email`::
An email address, delimited by angle brackets (`<>`).
If one or more of the author's names consists of more than one word, use an underscore (`_`) between the words you want to adjoin.
For example, the author of the following document has a compound last name.
[source]
----
include::ex-author.adoc[tag=2-mid]
----
.Result: Rendered author information when author has a compound name
====
image::author-compound.png[Compound author name attributes]
====
Alternatively, the author and email attributes can be set explicitly in the header.
[source]
----
include::ex-author.adoc[tag=attr]
----
.Result: Rendered author information when author and email attributes are explicitly set
====
image::author-email-long.png[Author and email attributes]
====
The `html5` and `docbook` converters can convert documents with multiple authors.
Multiple authors and their emails are separated by semicolons (`;`) when they're listed on the same line.
[source]
----
include::ex-author.adoc[tag=multi]
----
<1> To reference the additional authors in the document body, the author attributes are appended with an underscore (`+_+`) followed by the position of the author in the author information list (i.e. Lazarus het Draeke is the second author in the list so his author attributes are appended with a 2).
.Result: Rendered author information when document has multiple authors
====
image::multi-author.png[Multiple author and email attributes]
====
////
If you want to enter multiple authors and their emails as attribute entries, the attribute names are as follows:
[source]
----
include::multi-author-email-long.adoc[]
----
.Result
====
image::multi-author-email-long.png[Multiple author and email attributes]
====
Where does `authored` (empty string '' if {author} or {email} defined) fit in?
////
==== Attribute references in the author line
The implicit author line was not intended to support arbitrary placement of attribute references.
While attribute references are replaced in the author line (as part of the header substitution group), they aren't substituted until _after_ the line is parsed.
This ordering can sometimes produce undesirable or surprising results.
It's best to use the author line strictly as a shorthand for defining a fixed author and email.
If you do need to use attribute references in the author or email value, you should revert to defining the attributes explicitly using attribute entries.
.Using attribute references to set author and email
[source]
----
= Document Title
:author_name: ACME Industries
:author_email: info@acme.com
:author: {author_name}
:email: {author_email}
----
Just remember that the author line is for static text.
Once you graduate beyond static text, you should switch to using attribute entries to define the built-in author attributes, which will give you much more power.