do something better with <br/> tags

[hossman]

This code has been in the jsoup cleanup code since before i started working with it...

// remove breaks -- TODO: why?
elements = docOut.getElementsByTag("br");
for (Element element : elements) {
  element.remove();
}

...and is currently the cause of some really ugly formatting in some files -- notably collections-api.adoc -- but a quick experiment in removing it and regenerating the adoc files doesn't look like a slam dunk: that may cause more problems then it solves.

Filing this issue as a reminder to look into this later -- even if it's not worth trying to make the code smarter, it's probably worth making a list of affected pages / sections so we can audit them after final conversion

[ctargett]

The API pages will all have this problem, and I'm content to leave them to cleanup.

I'd be interested to know if you've seen other areas where it's a problem, besides the lists of API calls that aren't actually lists.

[hossman]

I've created the keep-br-tags branch as a way to quickly compare what the changes would be if we stoped stripping br tags as part of the conversion -- see 6f2ca17c1cebe57c7641e6eb140d63abcd6868e9 for a list of impacted files.

There are lots of places where leaving these br tags in makes the formatting worse, here's a short summary of places where it obviously seems to makes the formatting better...

• collections-api.adoc
  • "API Entry Points" list section at the top
  • also the way input example descriptions are sometimes in the same para as the input "header" (which is really just bold text)
• configsets-api.adoc
  • api entry points list
• cross-data-center-replication-cdcr-.adoc
  • api entry points lists (there are two of these sections)
• defining-fields.adoc
  • used to "list" attribute values in table
• fastvector-highlighter.adoc
  • poor mans paragraphs
  • used to "list" param keys in table
• field-properties-by-use-case.adoc
  • "list" of footnotes
• field-type-definitions-and-properties.adoc
  • used to "list" param keys in table
• function-queries.adoc
  • used to "list" diff example usages in table
• other-parsers.adoc
  • multiline text in a table cell (that should probably be in a code block?)
• pagination-of-results.adoc
  • poor mans paragraphs
• running-your-analyzer.adoc
  • poor mans paragraphs
• schema-api.adoc
  • api entry points list
  • also one output example description is in the same para as the Output Content "header" (which is really just bold text)
• standard-highlighter.adoc
  • used to "list" param keys in table
• uploading-data-with-index-handlers.adoc
  • poor mans list
  • used to "list" diff example usages in table
• uploading-data-with-solr-cell-using-apache-tika.adoc
  • poor mans list
• working-with-dates.adoc
  • poor mans list
• working-with-external-files-and-processes.adoc
  • plain text file example missing line breaks (should probably be a code block)