search

asciidoctor / docbookrx

(An early version of) a DocBook to AsciiDoc converter written in Ruby.
MIT License
22 stars 49 forks source link

Refactor DocbookRX to first create an internal model before creating output #51

Open mrietveld opened 8 years ago

mrietveld commented 8 years ago

@mojavelinux One of the problems I'm increasingly encountering is the lack of state. This makes dealing with whitespace, continuations and nested elements, among others, hard to deal with. I've tried fixing it with adding more fields, but these fixes end up being band-aids on a larger wound..

I'd like to refactor docbookrx so that it first creates an internal model of the AsciiDoc document before "printing".

Any objections or other issues that I might be missing?

(BTW, I'm definitely not totally sure about this -- I'm just running into a lot of edge cases that seem to suggest that this would be a better approach than what we have currently).

mojavelinux commented 8 years ago

I've sensed this strain for some time and anticipated that there'd come a time when we would have to address it. As you've probably observed, there are numerous places we have to push hints forward like adjoin_next, list_depth, continuation and so forth. These hints are flimsy and often lack sufficient context.

I like code that speaks at a high level. I think that makes it easier to follow. I'm not sure yet whether we need an internal model or just an intelligent writer object to accomplish that. I'm interested to see what you propose. I'm certainly not trying to hold on to the current approach. As the prototype, it is natural that it will evolve.

Regarding the intelligent writer, I'm imagining something like an XML/DOM writer. That way, we don't worry so much about blank lines. Instead, we say "new block" or "continue list" and it knows what is needed to make that happen.

mrietveld commented 8 years ago

Thanks for suggesting the "intelligent writer" pattern, I hadn't thought of that. That approach would actually be a lot easier (and easier to read) instead of having to interweave the model maintenance/build code in the visit methods. Once I get enough details down, I'll submit a PR for review (not 100% done, but enough to pass some tests and that the overall picture is clear).