Creating a dedicated table in the user guide for intrinsic attributes

[rockyallen]

Add an extra table in Appendix B so that eventually all available attributes can be found there. I would also suggest renaming Appendix B to "Predefined Attributes" to make this clear.

[rockyallen]

See also #481

[rockyallen]

Can you confirm my interpretation of "instrinsic attribute" please:
User manual, section 12.2 "... A number of attributes and values are automatically used when the Asciidoctor processor renders a document. These attributes are called intrinsic attributes. For example, you do not need to set the normal attribute on a basic paragraph because it is set by an intrinsic attribute. But when you want a paragraph to have a different style, such as TIP, you set the TIP attribute on a paragraph and TIP will override the intrinsic normal attribute. Intrinsic attributes can be overridden or unset from the command line or within the document."

so it includes all attributes that affect the processing.
They may or may not have default values.
I don't think it includes TIP and normal, because TIP is not an attribute; it is the value of the "style" attribute, which is the first positional attribute for a paragraph.

The full list is then:
Attribute-missing
attribute-undefined
copycss
customcss
customjs
deckjs_theme
deckjs_transition
docinfo
docinfo1
docinfo2
experimental
hardbreaks
iconsdir
idprefix
imagesdir
indent
last-update-label
leveloffset
linkcss
menu
navigation
noheader
No-header-footer
notitle
nowrap
noxmlns
numbered
prewrap
role
scriptsdir
sectanchors
sectlinks
sectids
showtitle
source-highlighter
split
status
stem
style
stylesdir
stylesheet
title
toc
toclevels
toc-placement
toc-position
toc-title
version-label

Also, are "set" and "defined" synonyms?

[mojavelinux]

"you do not need to set the normal attribute on a basic paragraph because it is set by an intrinsic attribute."

I think the user manual is creating some confusion here. I would described this example more as "intrinsic behavior" and thus a separate topic.

Intrinsic attributes are simply attributes that are defined by default that you can reference using the {name} syntax. These aren't to be confused with node attributes (usually block attributes), which affect the behavior of a block. The example I cited is an example of a block attribute.

[mojavelinux]

Also, are "set" and "defined" synonyms?

Yes. Feel free to make it consistent by choosing one or the other.

[mojavelinux]

TIP is not an attribute; it is the value of the "style" attribute,

Exactly. We need to be careful to talk about that in a separate section.

Whenever we talk about an attribute that can be reference using {name} we are talking about a "document attribute". These are the "variables" in AsciiDoc.

[mojavelinux]

Committed as 9940616.

[mojavelinux]

Amazing work @rockyallen! I was able to come in and add detail where it was missing, but you made it easy.

We are still missing a few attributes.

• hide-uri-scheme - hides the URL scheme for all links (can be set anywhere in document); not set by default
• relfileprefix - the prefix added to relative xrefs; not set by default
• coderay-linenums-mode - sets how line numbers are added to source listings (table or inline); table by default
• pygments-linenums-mode - sets how line numbers are added to source listings (table or inline); table by default
• authorinitials - derived from the author name by default, but can be set explicitly; header only
• orgname - sets the orgname meta in the DocBook backend; not set by default; header only
• man-linkstyle - used to style the links in the manpage output; default blue R <>
• title - an alternate way to set the doctitle; header only
• title-separator - the character used to separate the main title and subtitle in the document title; header only
• docinfodir - the location where Asciidoctor will look for docinfo files; defaults to directory of input file; header only
• docinfosubs - the substitutions that get applied to docinfo content; not set by default; comma-separated list of substitution names; header only
• skip-front-matter - indicates the Asciidoctor should consume YAML-style front matter at the top of the document and store it in the front-matter attribute; not set by default; header only
• cache-uri - indicates that Asciidoctor should cache content read from URIs; not set by default; header only

I'm pretty confident that all the remaining attributes (at least for the built-in converters).

[mojavelinux]

Here's the attributes appendix as it now stands.

http://asciidoctor.org/docs/user-manual/#builtin-predefined-attributes

I think we should move the intrinsic attributes to this appendix too so that all the document attributes are together. wdyt?

In the process, we've coined the following terms to differentiate the various attributes:

• built-in - reserved attributes used to control processing
• intrinsic - dynamic attributes that pertain to or give information about the runtime environment
• predefined - convenience attributes for content replacements

Does that sound right to you? What do you think we should call this appendix to encapsulate that list?

cc: @jaredmorgs

[mojavelinux]

I'd just like to say thank you @rockyallen for finally making this happen. Not only is this appendix going to help just about every user of Asciidoctor, it also gives me a clarity I didn't have before.

[mojavelinux]

Two more:

• mansource - meta about the manpage source (the source to which the manpage pertains); not set by default; header only
• manmanual - assigns a name to the manpage to display in the footer; not set by default; header only

[rockyallen]

No problem-and thanks for clearing up my mess. One day I will work out how to use Git...

[jaredmorgs]

You're not the only one who had problems with this. 😉

Great job with your contributions!

On Sat, 27 Feb 2016, 03:57 rockyallen [email protected] wrote:

No problem-and thanks for clearing up my mess. One day I will work out how
to use Git...

—
Reply to this email directly or view it on GitHub
#480 (comment)
.

Sent from Mobile.

[mojavelinux]

It's just a matter of documenting how to do it. This experience is helping me understand how to explain it.

[mojavelinux]

I'm also open to using "implicit" instead of "intrinsic". These two words are pretty close in meaning and it all depends on how you read it.

[rockyallen]

Happy to add the extras listed above, but could someone reopen this issue please? I don't think I can.

Re 'intrinsic': the definition above is "dynamic attributes that pertain to or give information about the runtime environment". The active words are 'information', 'runtime' and 'environment'. How about one of those, maybe runtime?

Re the appendix title: Just "Attributes", or "Attribute definitions"?

Side issue:
What do we call attributes that the user creates? The manual never explicitly describes them, but gives an example in "13.4. Setting attributes on a document" where it is referred to as a "header attribute". Do we need a term? if so, maybe "variables", "user attributes", or "user defined attributes".

[mojavelinux]

What do we call attributes that the user creates?

I like "user-defined attributes" the best.

[mojavelinux]

Re the appendix title: Just "Attributes", or "Attribute definitions"?

How about something like "Attribute catalog", "Attribute index", "Attribute glossary" or "Attribute reference tables"?

[mojavelinux]

I had a discussion with @graphitefriction and we concluded that the most fitting name for the attributes that get automatically assigned based on the conditions under which the document is processed are "Environment attributes".

environment - the aggregate of surrounding things, conditions, or influences

I think it's a perfect fit and it is also a familiar concept/term for technical people.

[mojavelinux]

Under that definition, I think that user-home definitely belongs in the "Environment attributes" section.

Btw, I am intentionally avoiding the use of the word "variable". Technically, attributes are variables, but in AsciiDoc world we call "variables" attributes and therefore should remain consistent.

[mojavelinux]

I can't believe it, we almost have all the attributes documented! I have a few I'm going to add to the intrinsic (soon to be environment) table and then I think we'll have them all.

One issue that remains is that we'll need to document the EPUB3 and PDF attributes. I think it makes sense to add a new subsection in the table for each of these two converters (just below HTML styling).

[mojavelinux]

In that spirit, I think we should move all the manpage attributes (except manname-title) to a dedicated section for "Manpage" (in some cases, the attribute pertains to the manpage doctype and in other cases to the manpage converter, but I think it's reasonable to group them).

[mojavelinux]

We might also want to think about creating a group for section-related attributes since there are quite a few of those:

• sectids
• sectnums
• sectanchors
• sectlinks
• idprefix
• idseparator
• sectnumlevels

wdyt?

[rockyallen]

Maybe, but if we carry on grouping at finer levels won't we end up just
duplicating the tables that are already in the main body?

I don't know if it is possible to use it with Asciidoctor, but I really
like sortable.js (http://www.kryogenix.org/code/browser/sorttable/). The
group could be turned into a column then sorting would give the
attributes sorted by group or by name.

On 28/02/16 00:24, Dan Allen wrote:

We might also want to think about creating a group for section-related
attributes since there are quite a few of those:

• sectids
• sectnums
• sectanchors
• sectlinks
• idprefix
• idseparator
• sectnumlevels

wdyt?

—
Reply to this email directly or view it on GitHub
#480 (comment).

[mojavelinux]

I think there is definitely a risk of using too many categories, but keep in mind that the value of this table is that all the information is in one place. I think the key with the categories is to try to keep the groups balanced. The control/formatting group is too large atm, which is why I think moving the man attributes and the section attributes to their own category strikes the right balance. I'm going to give it a try and see how it feels. If it seems like too much, we can always roll back.

I don't know if it is possible to use it with Asciidoctor, but I really like sortable.js

Me too. I've been thinking about adding that to Asciidoctor ever since I started working on it. We could add it as an extension to the user manual so it's available sooner rather than later.

Interesting to note that it is implemented in docgist. See http://neo4j.com/graphgist/8e1d6ff9-f7fa-4c99-9c5d-ecb94ba46d81.

[mojavelinux]

To clarify why this issue is still open, we want to:

• move (or copy) the table of environment attributes into this appendix
• rename the appendix so it accounts for all attribute types present

[mojavelinux]

We're also still missing a few attributes:

• tabsize (will be added as part of Resolves issue #434 AsciiDoc Python migration guide #540)
• css-signature
• toc-class
• firstname, lastname, middlename
• doctitle and title (title is used in place of doctitle in certain cases)
• pagewidth (DocBook only)

I'm happy to add entries for these. The good news is that I can't find any more attributes that aren't mentioned. We're almost there!!

I also think we should be more specific about which <meta> tags are added for each metadata attribute. Right now it's kind of vague.

[mojavelinux]

I'm keen on getting these two changes made:

• move (or copy) the table of environment attributes into this appendix
• rename the appendix so it accounts for all attribute types present

Shall I open a separate issue and close this one @rockyallen?

[rockyallen]

Sorry, got distracted-I will do it tonight.

• Title "Attribute Catatog"
• Bring in environment variables first so it goes environment, built-in, predefined.
  We should also use the new terminology consistently - new issue.

[rockyallen]

See PR

[mojavelinux]

Thanks @rockyallen!

I added an intro to the Attribute Catalog and also revised the description of the Environment Attributes a bit. You can see the result here: http://asciidoctor.org/docs/user-manual/#attribute-catalog

The only think left in this issue is to document the doctitle and title attributes. I'll take care of that next.

[mojavelinux]

At last, we're done!

http://asciidoctor.org/docs/user-manual/#attribute-catalog

From this point forward, we'll address any improvements to the entries in these tables through dedicated issues. Great work team! @rockyallen @jaredmorgs

[mojavelinux]

@rockyallen are you on Twitter by chance? I like to give contributors a shout out there to help promote their great work.

[rockyallen]

Thats very kind, but I'm a bit of dinosaur - I don't even have a mobile
phone! Its good to feel involved though.

On 15/03/16 21:58, Dan Allen wrote:

@rockyallen https://github.com/rockyallen are you on Twitter by
chance? I like to give contributors a shout out there to help promote
their great work.

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#480 (comment)

[mojavelinux]

I'm very glad you're involved! I just wanted to be sure I wasn't missing you on Twitter. To fill you in, I posted the following two messages related to this issue:

A docs team is forming around Asciidoctor and I couldn't be more thrilled. Docs are code too.
— https://twitter.com/mojavelinux/status/708205918350082048

&

At last, the catalog of known document attributes in Asciidoctor is fully populated. \o/ Feedback welcome.
— https://twitter.com/mojavelinux/status/709620425903353857

[jaredmorgs]

Ever since you started contributing to the docs, I've wondered what the
motivating factor was that made you lend your excellent Tech Comm skills to
the project.

Was it the links to all the bug IDs in the User Guide that made you open
PRs? Or was it something else?

Either way, I'm so glad you're here lending your skills to the project.

It's fantastic!

Sent from Mobile.

[mojavelinux]

Answers to these questions could help us lower barriers for contributors, improve the workflow and provide necessary guidance and motivation. In other words, we want to do whatever we can to pique the interest of those that want to be involved.

[rockyallen]

(blushes) You all do a great job on a great bit of software. I use it for my day job, and I wanted to give something back. I tried contributing to the code but learning a new language was a bit much for me; writing is easy, especially when Asciidoctor has such a good documentation set already.

Re the pointers - yes they are a prompt to areas that need input, but mostly I chose areas that were giving trouble at work - documenting being a good way to learn.

The biggest barrier to contributing for me was Git/GitHub which I found (find!) very challenging. Do you think there is a way to to simplify it, or give more hand-holding for newbies?

Thanks

Rocky

[mojavelinux]

Thanks to you, the documentation set is drastically improving, not to mention more complete. We can all be proud of that.

From your feedback, it seems like the most valuable tool is a link from the documentation to an open issue. That supports the case that you are reading the documentation for your own needs and you get prompted where you can jump in to help. In other words, it flags where paths cross and gives a next action.

Do you think there is a way to to simplify [git/GitHub], or give more hand-holding for newbies?

That's the million dollar question. I love git & GitHub because it gives us a powerful workspace in which to collaborate. However, there are still some incredibly sharp edges that present a big challenge, for writing especially.

I think the solution here is provide a very clear and well-written contributing guide for writers (see #468 and #403).

When I think about how I work, there are just a few techniques I use over and over without ever running into problems. I am far, far, far from a git master. It's just that I know exactly what everyday commands to issue so that I avoid getting hung up. The key is to figure out how to describe those techniques so that anyone coming along can follow them. (how to work with branches, when to use amend, when to use rebase, how to fast-forward merge to master, send a pull request to another pull request, etc). It's going to be a fun challenge.

Beyond that, there is a chance a tool will come along that works on top of GitHub that hides a lot of this away. But I have yet to find such a tool.

[mojavelinux]

And, once again, thank you Rocky!