[
https://issues.apache.org/jira/browse/SOLR-10883?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16058096#comment-16058096
]
Cassandra Targett commented on SOLR-10883:
------------------------------------------
I had an offline discussion with Steve about this. The changes to validate
.adoc files are fine IMO, but are only a drop in the bucket as far as what can
go wrong with these files.
There are already two validations that happen when the docs are built:
* the Jekyll and Asciidoctor-pdf tools that we use to build the HTML and PDF
versions respectively will WARN if files are malformed. The two most common
I've seen are when section levels are out of order and when a section doesn't
include a "part" (see SOLR-10297 for more discussion about these)
* After the docs are built, the {{check-links-and-anchors}} target validates
that all the links between pages adhere to the proper format to be sure they
work in the PDF, and makes sure there are not duplicate section headings on
different pages so inter-doc links don't get confused.
I don't expect there to be a lot of devs who build the docs locally before
committing their changes, but it would be nice if the Ref Guide build had the
additional validation of what you want to put in precommit; by the same token,
it would be nice if precommit checked the links and anchors that's now only
done during the build (the most recent Jenkins Ref Guide build failure was
caused by that check not being run).
I also have a list of stuff I'd like to add to validation, just as warnings -
more along the lines of enforcing/suggesting some style consistencies where
feasible.
If you go ahead and commit your changes here, I can look at adding precommit to
the Ref Guide build. Then maybe we can add the check-links-and-anchors to
precommit if that makes sense to others also.
> Ref guide: some replacement substitutions, e.g. => to right arrow, are
> rendered invisibly in the PDF
> -----------------------------------------------------------------------------------------------------
>
> Key: SOLR-10883
> URL: https://issues.apache.org/jira/browse/SOLR-10883
> Project: Solr
> Issue Type: Bug
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation
> Reporter: Steve Rowe
> Assignee: Steve Rowe
> Attachments: Screen Shot 2017-06-12 at 7.23.07 PM.png,
> SOLR-10883.patch, SOLR-10883.patch
>
>
> {{=>}}, {{<=}}, and {{<-}} are rendered as invisible in the PDF. These
> “replacement substitutions” aka “textual symbol replacements” (
> http://asciidoctor.org/docs/asciidoc-writers-guide/#replacements ) render as
> invisible characters in the PDF, though they are visible in the HTML format,
> when substitution is in effect.
> This is only a problem outside of code blocks (e.g. {{-->}} close comment
> syntax in XML is never improperly substituted).
> In the screenshot below, a table from the
> CharFilterFactories|solr.MappingCharFilterFactory section is shown in the
> HTML format on the left, and in PDF format to the right; in the PDF format
> the {{=>}} is invisible.
> !Screen Shot 2017-06-12 at 7.23.07 PM.png|width=800!
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
