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
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.
|