MPR#7352,7353: ocamldoc, better paragraphs in html #804
Conversation
| <br> | ||
| <b>Author(s):</b> : Florian Angeletti<br> | ||
| <b>Version:</b> : 1<br> | ||
| </div> |
There was a problem hiding this comment.
Are these <br> are gone from the other PR ? Somehow all this should also be put in a <p>.
There was a problem hiding this comment.
If you mean the documentation tags,
Author(s): : Florian Angeletti
<br>
Version: : 1
then yes, all the <br> will be gone once combined with the other pr, and this fragment will be replaced by
<ul class="info-attributes">
<li> <b>Author(s):</b> : Florian Angeletti </li>
<li> <b>Version:</b> : 1 </li>
</ul>
There was a problem hiding this comment.
Ok cool. I'm personnaly not very fond of tags and do not use them except for @raise but note that alternatively this could be replaced by a definition list.
<dl class="info-attributes">
<dt>Author(s)<dt><dd>Florian Angeletti</dd>
....
There was a problem hiding this comment.
(However they are not that convenient to style so it may not be such a good idea)
There was a problem hiding this comment.
After taking the time to look at this question, the semantic of description list is indeed a better fit , but the default rendering seems quite opiniated and not that easy to style.
For instance, going back to the current rendering for documentation tags seems to require fiddling with either floating attributes or ::after pseudo-elements. I also could not find a simple way to handle the possibility to have multiple <dd> descriptions by <dt> data term.
Consequently, I am leaning towards keeping the unordered list for now.
|
A few months later, where are we with this PR and its companion #802 ? |
This commit replaces most of the use of <br> tags in ocamldoc html backend by more meaningful tags, in order to improve the themability of the generated html code.
Octachron
force-pushed
the
ocamldoc_regular_<p>
branch
2 times, most recently
from
591b859
to
cf51bd4
Compare
Octachron
force-pushed
the
ocamldoc_regular_<p>
branch
from
cf51bd4
to
d069dbe
Compare
Remove redundant opens
Fix interf graph for exceptional path.
Co-authored-by: Cuihtlauac ALVARADO <cuihtmlauac@tarides.com>
Companion PR to #802, this PR makes the generation of paragraph
<p>tags in ocamldoc html backend much more regular.In particular, it fixes the problem of untagged text reported in MPR#7353 and avoid emitting space-only paragraph as reported in MPR#7352. See www.polychoron.fr/ocaml-nonmanual/pr804, for example of the improved html output.
Paragraph.htmlshowcases the general improvment with respect to MPR#7353 (and have been added to ocamldoc testsuite) andAstring.htmlis directly the example reported in MPR#7352 by @dbuenzli.Before this PR, ocamldoc mainly let the handling of the paragraph tags to the care of the browser: it only emitted opening
<p>tag at new line, and never closed them. Consequently, the first text element of comment were never enclosed in a paragraph tag. Moreover, for each comment containing elements that cannot be contained in a paragraph (e.g. a list), the next paragraph was also not enclosed in a paragraph tag.This PR implements a more coherent handling of paragraph within the html generator, opening and closing the corresponding paragraph. As a bonus, the new code also avoids to emits space only paragraph. However, currently, space-only paragraphs are recognized using the trim function, and would work only with ascii spaces and new lines.
Note that the style of the generated documentation have been partially adapted, but more tweaks would be needed depending on the potential merge of #802.