A bit of radio silence on this, but Hoss & I have made some progress
since I first made the proposal last month.

Hoss helped me with scripts to make the conversion process easier and
more automated. The goal is to do this one time as quickly as
possible, so it was worth spending a bit of time on trying to get it

Hoss also worked on a process that will automatically create a
hierarchy of pages for sidebar navigation and as the basis for the PDF
output (more on that below).

This has allowed us to make a demo of the entire Ref Guide online, at

A PDF version is available at
(beware, it's currently 27Mb).

There are a few known issues that we will only be able to resolve
manually, once we actually do the conversion:

- Nested blocks of content in tables (like code blocks or NOTEs, etc.)
break the rows.
- Nested ordered lists (like 1, 2, a, b, 3, 4) get converted as a bad
quasi-ordered list (like 1, 2, 2, 2, 3, 4).

For both of these items, TODOs have been added to the new .adoc format
files so we can manually fix the problems.

Additionally, we are working through some bugs with inter- and
intra-document links. These are problematic, and we need to spend a
little bit more time on them. And we have a few other small issues
remaining, tracking (for now) in the Github repo:

We'd like your help with two things before moving to the next phase:

- Review the full guide online or in PDF and look for conversion
problems we may have overlooked so far (problems that aren't the ones
I just mentioned above).

- In order to automate building the sidebar nav & PDF, every parent
document includes a list of its children. We will need to maintain
this, although can add some pre-pub scripts to check that all pages
are listed in some parent document. Do you think this is workable?
Have a better idea?

For a couple of examples, see:

Note the "page-children" at the top. That contains the list of
children pages that will be pulled into nav and the PDF.

Depending on your feedback, I'm hopeful the next phase will include
fixing some of the remaining issues, creating a branch to bring the
pages into the project, and figuring out where to host the pages


To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org

Reply via email to