Support paragraphs

[amolenaar]

(this is a spin-off of issue #30)

Currently the wiki engine translates line endings in wiki text with line breaks (<br/> tags) in the html output. This is a legacy feature.

From an HTML point of view, text paragraphs should be in paragraph (<p></p>) tags. This gives more semantic meaning to the text and also allows users to style the text better, especially when combined with other elements (tables, pre-formatted text). It should also lead to less cumbersome markup, since you can simply add one or more newlines between a piece of text and it looks just fine once rendered.

The markups popular today (markdown, textile, reStructuredText) separate paragraphs by a blank line (2 newlines).

@stanio put some work in it already and that looks rather okay.

[jediwhale]

Thoughts on how/when to deploy? This would be a breaking change. There's probably other breaking changes that would clean up wiki markup - do we plan for a breaking parser release at some point? or figure out a plug-in or configuration mechanism so users can move to new markup behavior at their choosing?

[amolenaar]

I personally feel the breaking will be minimal: if you want to create 2 paragraphs now, you put a blank line between the paragraphs. This is where the separation is done. On the other hand, if you use constructs like:

some test
- list item 1
- list item 2

that will display as

some text - list item 1 - list item 2

when using paragraphs. That's probably the biggest problem here. (is it?)

Making it configurable may be a good idea. At least to the extend where FitNesse can revert to the old parser behaviour if the user sets a specific property. I feel we have to move forward (implement proper paragraph syntax as the default). Having a safety net for existing test suites (a configuration or system property of some sort) would be a nice fallback option though.

I already implemented some minor fixes in the parser while I was working on the new layout/templating. I can't think of that many changes that would justify a "big bang" breaking release. Gradual improvement would have my preference.

The ReleaseNotes page can be used to make users aware of this change. After a version update a message is displayed that notifies the users to check this page for changes.

[jediwhale]

Here's a start at the requirements:

Text separated by two newlines is wrapped in paragraph: some\n\nstuff -> <p>some</p><p>stuff</p>

Text separated by one new line is line break?: some\nstuff -> some<br/>stuff'

Paragraph wrapping starts and ends with block elements?: !1 head\nsome\n\nstuff\n!1head -> <h1>head</h1><p>some</p><p>stuff</p><h1>head</h1>

[jediwhale]

Question:

Is all text wrapped in paragraphs or only if adjacent to blank line? !h1 head\nstuff\n!h1 head\n -> <h1>head</h1>stuff<h1>head</h1> or <h1>head</h1><p>stuff</p><h1>head</h1>

[amolenaar]

Text separated by one new line is line break?: some\nstuff -> some
stuff'

I would prefer it being rendered as <p>some stuff</p> (like Markdown a.o. does it), but I guess that jeopardizes many of the existing pages that rely on newlines being translated to <br/>. Having a !define variable to toggle this would be great (just like graceful name rendering is triggered by REGRACE_LINK).

Is all text wrapped in paragraphs or only if adjacent to blank line? !h1 head\nstuff\n!h1 head\n -> <h1>head</h1>stuff<h1>head</h1> or <h1>head</h1><p>stuff</p><h1>head</h1>

I think the second options makes sense. In the first case we still end up having text without semantic context (i.e. <p> tag).

[jediwhale]

We could use styles to preserve existing appearance for single line breaks? e.g. <p class="single">stuff</p> Does this make sense?

[amolenaar]

It would be better to put a plain <br/> in. In the markdown-ish way you want the text to be displayed in one paragraph (replacing single newlines with spaces, basically). Having a separate class does not help here, IMHO.

[amolenaar]

Hmm... There's still some unfinished business here ;).

To summarize the above:

1. paragraphs are a neat idea
2. We need some way to support legacy rendering (either by a class or via plain BR's in the content)

I suppose it would make the renderer a lot simpler if it has to render only one format and leave the representation (e.g. preformatted+line-wrapping) to the browser. Using a class (at body level) could be a solution here.

[jediwhale]

Haven't had any time for FitNesse for a while, should be able to start again soon. Thinking about a pluggable parser interface so we can let people keep old behavior when we release new versions.

On 2012-10-18 08:55, Arjan Molenaar wrote:

Hmm... There's still some unfinished business here ;).

To summarize the above:

1. paragraphs are a neat idea
2. We need some way to support legacy rendering (either by a class or via plain BR's in the content)

I suppose it would make the renderer a lot simpler if it has to render only one format and leave the representation (e.g. preformatted+line-wrapping) to the browser. Using a class (at body level) could be a solution here.

— Reply to this email directly or view it on GitHub https://github.com/unclebob/fitnesse/issues/84#issuecomment-9567341.

Cheers, Mike Stockdale

/fit/Sharp http://fitsharp.github.com Syterra Software Inc. http://www.syterra.com

[amolenaar]

Cool. The property can be put in the page's properties.xml :)

[amolenaar]

Is this a candidate for the spring release?

[jediwhale]

I am doing some preliminary work on this. Probably a few months away.

On 2013-03-21 15:50, Arjan Molenaar wrote:

Is this a candidate for the spring release?

— Reply to this email directly or view it on GitHub https://github.com/unclebob/fitnesse/issues/84#issuecomment-15267825.

Cheers, Mike Stockdale

/fit/Sharp http://fitsharp.github.com Syterra Software Inc. http://www.syterra.com