search

ctargett / refguide-asciidoc-poc

Proof of concept of Solr Ref Guide converted to asciidoc format & using Asciidoctor for publishing
2 stars 4 forks source link

do better conversion of admonishments #8

Closed hossman closed 7 years ago

hossman commented 7 years ago

"Note" boxes are currently getting converted very trivially to "Note:", but we're definitely losing data about things like what the title of those boxes were, and that can/should be preserved in the final adoc.

I'm pretty sure the current conversion code is also losing information about:

hossman commented 7 years ago

(Hmmm... i guess i don't know how to link a commit to an issue properly so that it automatically shows up as a PR? .. oh well)

In the linked commit 45f4b93 i've got admonishments working pretty well, but there are still some questions about what the confluence->adoc mapping should be ... @ctargett: your opinion appreciated...

the one outstanding question is the mapping between the (5) admonishment levels that adoc supports, and the (4) diff macros we use in the ref guide...

http://asciidoctor.org/docs/asciidoc-writers-guide/#admonitions https://cwiki.apache.org/confluence/display/solr/About+This+Guide

Based purely on the defailt icons, I've currently got the code using this mapping:

  • NOTE: confluence-information-macro-information
  • TIP: confluence-information-macro-tip
  • IMPORTANT: confluence-information-macro-warning
  • CAUTION: n/a
  • WARNING: confluence-information-macro-note

...but the icons can easily be changed in our templates, and this mapping doesn't really match the "order of importance" implied be the adoc refrence, so i'm not sure if we should bite the bullet and make some explicit changes while doing this conversion.

ctargett commented 7 years ago

I would have thought that IMPORTANT would map to confluence-information-macro-note, but looking at the default icons, it seems that IMPORTANT has an icon that is more like a warning. Now I recall being a little surprised by that another time too.

Considering the default, the mapping you propose seems pretty good. But now I'm also wondering if we should just map IMPORTANT to confluence-information-macro-note and change the CSS to use a different color & icon.

Or, maybe we should just map confluence-information-macro-note to CAUTION, since iconographically (a word? maybe not) that is how we've used it in Confluence.

ctargett commented 7 years ago

Looking a bit more at what icons are used, the WARNING and IMPORTANT both use a similar icon - an exclamation inside another shape (triangle and circle, respectively), but the WARNING has been given an orange color and IMPORTANT has been given red. That seems to imply that IMPORTANT is stronger than WARNING, which I really think goes against user expectation.

We could swap the colors, and maybe even replace the IMPORTANT icon with something like a lightning bolt (http://fontawesome.io/icon/bolt/). Then you could map the existing notes the way you initially expected.

(For posterity, INFO uses an 'i' icon in a circle (blue), TIP uses a lightbulb (black), and CAUTION uses a fire symbol (orange-ish red).)

hossman commented 7 years ago

We could swap the colors, and maybe even replace the IMPORTANT icon with something like a lightning bolt ...

I can change the mappings to anything we want, but I haven't been able to figure out anyway to redefine what icon gets used for which admonishment ... there are config attributes for changing the labels listed here: http://asciidoctor.org/docs/user-manual/#builtin-attributes (tip-caption, warning-caption, etc...) but when icons are enabled that only changes the HTML title attribute ... how do we change the icon itself? ... if that's all done via CSS, how do we do it so it also affects the PDF?

Speaking of the PDF: I didn't notice before, but something about this change has broken the way the PDF is generated ... the admonishments aren't rendering right, and apparently many section headers are also broken on this branch ? ... need to dig into that i guess.

hossman commented 7 years ago

Speaking of the PDF: I didn't notice before, but something about this change has broken the way the PDF is generated ...

part of the problem is fixed in 649db72e685bebf25a26cf399410c787cb66f299 on my for-pr/issue-8-admonishments branch (aparently i still don't understand automatic pull requests)

The other part of the problem is a much bigger issue: ctargett/refguide-asciidoc-poc/issues/13

ctargett commented 7 years ago

(aparently i still don't understand automatic pull requests)

I think part of the problem is you're still working on your fork. Would it be easier to just make branches on the parent repo (this one)?

Admonitions in the PDF are handled like this: https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#admonition. The names can be changed in the YAML config file.

ctargett commented 7 years ago

Here's what I think we should do for mappings. I've included the iconography used with these sections, just for reference.

I will commit a change to ref-guide.css and refguide-theme.yml to conform to the colors & icons I specified above in cases where I'm suggesting they be changed. @hossman you can just take care of the mapping in the conversion.

hossman commented 7 years ago

@ctargett mappings updated, re-opening for you to track icon/bgcolor config changes here as well