Documentation: primer: AsciiDoc link macro; and Asciidoctor #223
Conversation
Begin making proper use of the macro. Prefixing: - only where necessary - not with https: or mailto: URL schemes.
|
@mojavelinux – primary maintainer of the language – is emphatic. The |
Asciidoctor (not AsciiDoctor).
|
I think this has already been discussed and it was decided to keep the |
| [[asciidoctor-link-macro]] | ||
| === The link macro | ||
|
|
||
| This macro is not often needed. Use cases are https://docs.asciidoctor.org/asciidoc/latest/macros/link-macro/#when-to-use-the-link-macro[specified in Asciidoctor Docs]. |
There was a problem hiding this comment.
Amongst the few use cases:
- The target must be enclosed in a passthrough to escape characters with special meaning
… languages with non-latin …
Would passthrough apply?
Under Escape and Prevent Substitutions, Passthroughs begins:
A passthrough is the primary mechanism by which to escape content in AsciiDoc. …
HTH
|
We need to use the link macro, English is not the only language we're using in the documentation. |
|
What can be done to help readers understand the need? TIA Postscript: I mean, the perceived need to always add the |
– or, as a truly typed that part of the message:
|
|
Use: Instead of: Why put the same two times? |
Not exactly the same, but it's a good question. For a few months I was horribly, repeatedly, confused by the apparent repetition. If I recall correctly, this requirement to partially duplicate link lines at the head of each submission:
If not already properly documented, then it should be fairly easy to find relevant commentary (and then document the logic) … probably in the https://github.com/freebsd/freebsd-quarterly archive. |
|
@lsalvadore do you need to put that two times for something related to the "plain" format? About the PR by itselft, if you want to replace AsciiDoctor with Asciidoctor go ahead, np, but don't remove the link: macro, we need to put it to make the life more easier for translators. In some languages Asciidoctor don't recognize the links without the link macro |
|
Can we be less insistent about blanket application of the At least: for content that we know will not be translated. In addition to the endless frustration caused by making things more difficult to proofread – and the increased likelihood of errors before and after proofreading – there is (at least, for me) the frustration of not knowing exactly why the It will help to have a concrete example of wrongness as a result of not applying the prefix. Can someone point us towards an affected commit? If not a commit, then might something visible in Weblate (I'm not a user) help to understand the consequences? TIA |
|
No, it's easier to say apply everywhere than to allow places where it doesn't. Regarding the fact that there are things that are not going to be translated, I do not agree, all the documentation can and should be translated, English is not the only language that our users have. The reason, Asciidoctor in some languages such as Japanese or Korean (languages that we have in our documentation) need to have the macro to know that what is being indicated is a link and not a normal text. It's not something related to weblate, it's something related to Asciidoctor. I know that in Asciidoctor documentation say that this does not happen, but theory is one thing and practice is another. Right now I can't spend time looking for an example in Japanese or Korean where this happens, but I remember it being like this when I did the conversion from Docbook to AsciiDoc and had to redo the scripts that parsed all the content. |
Yes, we need that repetition for the email format of the status reports. |
|
Ok, so keep it, np |
|
Upgrade the commit to see what you're gonna commit please |
This comment was marked as resolved.
This comment was marked as resolved.
grahamperrin
changed the title
|
LGTM |
Asciidoctor (not AsciiDoctor). Reviewed-by: carlavilla, salvadore Approved-by: carlavilla Pull-request: #223
|
Closing here, thanks.
@mojavelinux visualised a theoretical example, which helped to jog my memory. Then:
– eventually, I found a handful of real cases in FreeBSD areas. At a glance, these cases are rare … one or two under https://docs.freebsd.org/ja/books/porters-handbook/porting-dads/#dads-intro:
EssentiallyBeware of a URL macro adjacent to a non-space character. With spaces (non-adjacent)Areas such the two below might be the result of confusion:
And so on. |
|
I remove myself from this PR, the amount of noise that is generated sometimes by things so trivial is terrible, having other much more important things to work on |
|
No less terrible:
If that's so trivial in the eyes of others, I'm in the wrong project. Enough said. |
Move towards proper use of the macro.
Prefixing:
Whilst here, lowercase d in Asciidoctor.
Postscript
tl;dr beware of a URL macro adjacent to a non-space character.