resolves issue #480 more attributes

[rockyallen]

Please check:

• skip-front-matter refers to front-matter, so added front-matter to metadata for want of anywhere else
• changed default for reffileprefix to empty because it seems like it should be
• couldn't find anywhere to link man-linkstyle to

[mojavelinux]

couldn't find anywhere to link man-linkstyle to

This attribute will first appear in Asciidoctor 1.5.5. See https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/converter/manpage.rb#L112

[mojavelinux]

Nice job!

[mojavelinux]

relfileprefix possibly related to <> ?

Absolutely. That section should be enhanced to cover this attribute as well. The relfileprefix attribute is designed for environments where relative paths need to be adjusted, such as in a web site that rewrites paths. In fact, we use it in the asciidoctor.org site. See https://github.com/asciidoctor/asciidoctor.org/blob/master/_config/site.yml#L22

To explain in more detail, relative files work fine when the output file location mirrors the input file. However, a common practice is to move files into their own folder so that the path to filename.html becomes /filename/ (format agnostic). Doing this breaks relative paths since the two files are no longer siblings. The relfileprefix attribute allows you to inject a path navigation (e.g., ../) so that relative files can find each other.

[mojavelinux]

Shall we open a new issue to document relfileprefix in <>?

[rockyallen]

Issue opened.
Happy to do it, but I will be offline for a few weeks.

Re "This attribute will first appear in Asciidoctor 1.5.5. See https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/converter/manpage.rb#L112"

makes me wonder about the versioning policy. I have been bitten a couple of times testing things out and finally realizing that they are not working because I am a version behind the manual, but this is the first time documenting something that doesn't exist yet. Is this enough of a problem that it needs solving? Either way, suggest hold off documenting man-linkstyle until 1.5.5 is released.

Option 1: Release the manual with the software so they are always in lock-step. But the Asciidoctor manual is constantly evolving, so that won't work.

Option 2: Adopt the Javadoc @SInCE tag. Would add a lot of visual clutter (and work).

Option 3: Strategically placed "new" or "1.5.4" flags. Combined with a statement near the top saying what version the manual is for, and "new" means "new-for-this-version". The tags relating to 1.5.4 would be removed as part of the 1.5.5 release, at the same time as adding 1.5.5 tags.

Option 4: Somewhere prominent (not necessarily in the manual) point out that that the manual refers to the latest release, and give the link to the release notes. That might be enough to put people on the right track.

Thoughts?

[mojavelinux]

Thanks @rockyallen! We'll certainly miss you! You have truly given the docs a huge boost...something that they really needed.

makes me wonder about the versioning policy.

I think the solution to this problem is AsciiBinder (or something akin to it). AsciiBinder is uniquely designed for exactly this scenario. I've opened an issue to explore AsciiBinder and other options. One thing is for sure. We need to organize the docs and user manual better so they are easier to work with.

Option 2: Adopt the Javadoc @SInCE tag. Would add a lot of visual clutter (and work).

I think this is a good idea even if we publish multiple versions of the manual. I think we can find a way to put it into the gutter so it doesn't cause too much clutter.

Option 4: Somewhere prominent (not necessarily in the manual) point out that that the manual refers to the latest release

This is what AsciiBinder is all about.

[mojavelinux]

See #519.