MPR#7351: ocamldoc html, use tags rather than <br> #802

Octachron · 2016-09-10T17:34:47Z

This PR proposes to replace all uses of the <br> tag outside of <code> in the ocamldoc html backend by more meaningful tags, in order to improve the themability of the generated html. See MPR:7351.

In particular, ocamldoc sometimes used <br> tags to separate elements of a list, they are now <li> elements with a specific class for the corresponding <ul>; or to separate different blocks, these block are now given their own <div> tag.

The manual and default ocamldoc css styles have been altered to keep the rendered html globally similar but could be tweaked further: for instance, the vertical margin for title elements could be increased to get back to the previous spacing.

@dbuenzli : if you have comments, criticisms or examples of documentation where the <br> were particularly problematic, they would be very welcome.

gasche · 2016-09-10T17:47:55Z

@Octachron could you maybe have a html rendering output example on your webpage that @dbuenzli could use to check stylesheet adaptability? Also, your Changes entry should credit @dbuenzli (at least "request by", possibly "review by" depending on how the discussion goes.)

I'm fine with the current state of the PR that seems mergeable, but I would just as well wait for you and @dbuenzli to converge to a state that you both like -- maybe the proposed state is already such -- instead of chaining smaller PRs to correct after the fact.

gasche · 2016-09-10T17:53:21Z

ocamldoc/odoc_html.ml

+          self#html_of_sees b' info.M.i_sees;
+          self#html_of_custom b' info.M.i_custom;
+          let s = Buffer.contents b' in
+          if s <> "" then


Here it would be easy to use Buffer.length b' = 0 and then Buffer.add_buffer b b instead of going through an intermediate string, but the code would be slightly more low-level and thus less harmonious with the rest.

Thanks for the idea. I was going with the flow of the rest of the code. Nevertheless, I do not think it is really worth it to preserve code harmony here, so I am adopting your idea.

dbuenzli · 2016-09-10T18:31:46Z

It's a little bit difficult to judge based on the code but it seems mostly right. One thing I didn't see is whether the <br> after the <hr> is gone.

dbuenzli · 2016-09-10T18:33:55Z

examples of documentation where the
were particularly problematic, they would be very welcome.

As I said in the MPR they were not problematic per se for rendering since I was simply setting them to display:none, it's more that they were getting in the way to express some CSS rules like hr + h1.

Octachron · 2016-09-10T19:57:32Z

@gasche Thanks for the remarks!

I have amended the Changes and make available the generated documentation for the stdlib at http://www.polychoron.fr/ocaml-nonmanual/pr802/.

@dbuenzli, the <br> after the <hr> is gone, see for instance Ast_mapper. However, there is an enclosing <div class="module-comment"> in the generated html for now. So the css rule to access the <h2> element would be in the current version hr + div.module-comment > h2.

gasche · 2016-09-10T20:05:53Z

Changes

@@ -18,6 +18,10 @@ Next version (tbd):
  a short description in overviews.
  (Florian Angeletti)

+- PR#7351: ocamldoc, use semantic tags rather than <br> tags in
+  the html backend
+  (Florian Angeletti, request and review by Daniel Bunzli )


"Bünzli" would be the correct spelling. (I now realize that @alainfrisch also spelled it wrong a couple of times, you could fix those occurrences.)

Thanks ! Let unicode unicode.

Fixed, sorry for the mistake.

dbuenzli · 2016-09-10T20:09:45Z

<div class="module-comment">

What is this div supposed to represent/enclose ?

dbuenzli · 2016-09-10T20:23:09Z

What is this div supposed to represent/enclose ?

If it's the rest of the module doc then I'd rather not have this. It's better to keep the nesting not too unwildely but rather classifying things wells. I'm fine with the structure: module preamble sequence of definitions/paragraphs/headers at the same level (which is what we had for now).

Octachron · 2016-09-10T20:29:21Z

The div encloses separated unattached (global) module comments. See for instance the cookie section in Ast_mapper.

dbuenzli · 2016-09-10T20:33:48Z

The div encloses separated unattached (global) module comments.

Is this new ? I don't think its useful and a good idea. Unattached module comments should simply come in as p and h's naturally in the document like you would find them in a literate program.

Octachron · 2016-09-10T20:45:26Z

Yes, this is new. I rather agree than it is less than ideal. I will scrap that, but the caveat here is that it will generate more untagged text to be fixed in MPR:7353

dbuenzli · 2016-09-10T20:50:28Z

The problem is that it makes the document and the styling selectors needlessly complex (as you have seen in the example above). It's really not a good structure for enabling simple stylesheets.

I will scrap that, but the caveat here is that it will generate more untagged text to be fixed in MPR:7353

Why more than previously ?

Octachron · 2016-09-10T20:57:50Z

It's really not a good structure for enabling simple stylesheets.

I would argue than even more than that, it did not reflect any meaningful intent from the documentation.

Why more than previously ?

I was unprecise: as much as in trunk currently, a little more than in the previous version of this PR.

edit: module-comment <div> 's have been scrapped and the stdlib documentation updated

xavierleroy · 2017-02-17T14:02:40Z

A few months later, where are we with this PR and its companion #804 ?

gasche · 2017-02-17T14:16:47Z

I think that both could be merged in trunk¹. @Octachron, would you be ready to do this yourself?

¹: in general, I would trust @Octachron's choices of where to go with the ocamldoc codebase, so I think it makes sense to be liberal there. One thing we should be careful about is respecting compatibility for authors of ocamldoc styles (this is where @dbuenzli's input is precious), and breaking compatibility is not necessarilly a blocker but should at least give pause. My non-expert understanding of the current situation is that there was an issue with the <div> change, that has now be fixed, and that the rest is rather innocuous from this perspective.

Octachron · 2017-02-17T18:08:58Z

@gasche: in this case, this PR does introduce some incompatibilities with existing extensive css styles that were trying to restore some semantic structure from the currently generated html. However, this PR would also make writing such extensive css styles much easier by improving the semantic structure of the generated html.

All things considered, I believe that the best course of action would be to merge soon in trunk and publicizes this changes to see if there is any adverse reactions; and would be ready to merge the two PR
(even moreso since I partially remember that the two PRs are not fully commutative).

gasche · 2017-02-17T18:11:30Z

Fine with me.

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.

More comments for domains

ocaml#802) Co-authored-by: Stephen Dolan <stedolan@stedolan.net>

…w simpler version) (ocaml#802) Co-authored-by: Stephen Dolan <stedolan@stedolan.net>

25188da flambda-backend: Missed comment from PR802 (ocaml#887) 9469765 flambda-backend: Improve the semantics of asynchronous exceptions (new simpler version) (ocaml#802) d9e4dd0 flambda-backend: Fix `make runtest` on NixOS (ocaml#874) 4bbde7a flambda-backend: Simpler symbols (ocaml#753) ef37262 flambda-backend: Add opaqueness to Obj.magic under Flambda 2 (ocaml#862) a9616e9 flambda-backend: Add build system hooks for ocaml-jst (ocaml#869) 045ef67 flambda-backend: Allow the compiler to build with stock Dune (ocaml#868) 3cac5be flambda-backend: Simplify Makefile logic for natdynlinkops (ocaml#866) c5b12bf flambda-backend: Remove unnecessary install lines (ocaml#860) ff12bbe flambda-backend: Fix unused variable warning in st_stubs.c (ocaml#861) c84976c flambda-backend: Static check for noalloc: attributes (ocaml#825) ca56052 flambda-backend: Build system refactoring for ocaml-jst (ocaml#857) 39eb7f9 flambda-backend: Remove integer comparison involving nonconstant polymorphic variants (ocaml#854) c102688 flambda-backend: Fix soundness bug by using currying information from typing (ocaml#850) 6a96b61 flambda-backend: Add a primitive to enable/disable the tick thread (ocaml#852) f64370b flambda-backend: Make Obj.dup use a new primitive, %obj_dup (ocaml#843) 9b78eb2 flambda-backend: Add test for ocaml#820 (include functor soundness bug) (ocaml#841) 8f24346 flambda-backend: Add `-dtimings-precision` flag (ocaml#833) 65c2f22 flambda-backend: Add test for ocaml#829 (ocaml#831) 7b27a49 flambda-backend: Follow-up PR#829 (comballoc fixes for locals) (ocaml#830) ad7ec10 flambda-backend: Use a custom condition variable implementation (ocaml#787) 3ee650c flambda-backend: Fix soundness bug in include functor (ocaml#820) 2f57378 flambda-backend: Static check noalloc (ocaml#778) aaad625 flambda-backend: Emit begin/end region only when stack allocation is enabled (ocaml#812) 17c7173 flambda-backend: Fix .cmt for included signatures (ocaml#803) e119669 flambda-backend: Increase delays in tests/lib-threads/beat.ml (ocaml#800) ccc356d flambda-backend: Prevent dynamic loading of the same .cmxs twice in private mode, etc. (ocaml#784) 14eb572 flambda-backend: Make local extension point equivalent to local_ expression (ocaml#790) 487d11b flambda-backend: Fix tast_iterator and tast_mapper for include functor. (ocaml#795) a50a818 flambda-backend: Reduce closure allocation in List (ocaml#792) 96c9c60 flambda-backend: Merge ocaml-jst a775b88 flambda-backend: Fix ocaml/otherlibs/unix 32-bit build (ocaml#767) f7c2679 flambda-backend: Create object files internally to avoid invoking GAS (ocaml#757) c7a46bb flambda-backend: Bugfix for Cmmgen.expr_size with locals (ocaml#756) b337cb6 flambda-backend: Fix build_upstream for PR749 (ocaml#750) 8e7e81c flambda-backend: Differentiate is_int primitive between generic and variant-only versions (ocaml#749) git-subtree-dir: ocaml git-subtree-split: 25188da

* Ood: Use ppx_stable for data processing Use PPX library ppx_stable to generate function translating metadata read from Yaml into ood data. https://github.com/janestreet/ppx_stable This ppx can be used to generate conversion functions between almost identical records. * Handle tool and video * Inline of_metadata parameters * Cleanup * Formatting * Cleanup * Add extra @@deriving * Cleanup * Formatting * Add removed calls to Utils.slugify Co-authored-by: Cuihtlauac ALVARADO <cuihtmlauac@tarides.com>

gasche reviewed Sep 10, 2016
View reviewed changes

Octachron mentioned this pull request Sep 11, 2016

MPR#7352,7353: ocamldoc, better paragraphs in html #804

Merged

Octachron force-pushed the ocamldoc_semantic_html branch from 68ea8bf to 53bca56 Compare March 15, 2017 12:31

Octachron added 2 commits March 15, 2017 15:26

PR#7351: ocamldoc html, use tags rather than <br>

9d97673

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.

PR#7351: test for ocamldoc documentation tags

6110ca5

Octachron force-pushed the ocamldoc_semantic_html branch from 53bca56 to 6110ca5 Compare March 15, 2017 14:30

Octachron merged commit cc905fa into ocaml:trunk Mar 15, 2017

vicuna mentioned this pull request Mar 14, 2019

ocamldoc should really stop generating br tags #7351

Closed

EduardoRFS pushed a commit to esy-ocaml/ocaml that referenced this pull request Dec 17, 2021

Merge pull request ocaml#802 from ctk21/domain_comments

cc63999

More comments for domains

stedolan added a commit to stedolan/ocaml that referenced this pull request Oct 25, 2022

Improve the semantics of asynchronous exceptions (new simpler version) (

a77f0dd

ocaml#802) Co-authored-by: Stephen Dolan <stedolan@stedolan.net>

sadiqj pushed a commit to sadiqj/ocaml that referenced this pull request Feb 21, 2023

flambda-backend: Improve the semantics of asynchronous exceptions (ne…

9469765

…w simpler version) (ocaml#802) Co-authored-by: Stephen Dolan <stedolan@stedolan.net>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MPR#7351: ocamldoc html, use tags rather than <br> #802

MPR#7351: ocamldoc html, use tags rather than <br> #802

Octachron commented Sep 10, 2016

gasche commented Sep 10, 2016

gasche Sep 10, 2016

Octachron Sep 10, 2016

dbuenzli commented Sep 10, 2016

dbuenzli commented Sep 10, 2016 •

edited

Loading

Octachron commented Sep 10, 2016

gasche Sep 10, 2016 •

edited

Loading

dbuenzli Sep 10, 2016

Octachron Sep 10, 2016

dbuenzli commented Sep 10, 2016

dbuenzli commented Sep 10, 2016 •

edited

Loading

Octachron commented Sep 10, 2016

dbuenzli commented Sep 10, 2016 •

edited

Loading

Octachron commented Sep 10, 2016

dbuenzli commented Sep 10, 2016

Octachron commented Sep 10, 2016 •

edited

Loading

xavierleroy commented Feb 17, 2017

gasche commented Feb 17, 2017 •

edited

Loading

Octachron commented Feb 17, 2017

gasche commented Feb 17, 2017

MPR#7351: ocamldoc html, use tags rather than <br> #802

MPR#7351: ocamldoc html, use tags rather than <br> #802

Conversation

Octachron commented Sep 10, 2016

gasche commented Sep 10, 2016

gasche Sep 10, 2016

Choose a reason for hiding this comment

Octachron Sep 10, 2016

Choose a reason for hiding this comment

dbuenzli commented Sep 10, 2016

dbuenzli commented Sep 10, 2016 • edited Loading

Octachron commented Sep 10, 2016

gasche Sep 10, 2016 • edited Loading

Choose a reason for hiding this comment

dbuenzli Sep 10, 2016

Choose a reason for hiding this comment

Octachron Sep 10, 2016

Choose a reason for hiding this comment

dbuenzli commented Sep 10, 2016

dbuenzli commented Sep 10, 2016 • edited Loading

Octachron commented Sep 10, 2016

dbuenzli commented Sep 10, 2016 • edited Loading

Octachron commented Sep 10, 2016

dbuenzli commented Sep 10, 2016

Octachron commented Sep 10, 2016 • edited Loading

xavierleroy commented Feb 17, 2017

gasche commented Feb 17, 2017 • edited Loading

Octachron commented Feb 17, 2017

gasche commented Feb 17, 2017

dbuenzli commented Sep 10, 2016 •

edited

Loading

gasche Sep 10, 2016 •

edited

Loading

dbuenzli commented Sep 10, 2016 •

edited

Loading

dbuenzli commented Sep 10, 2016 •

edited

Loading

Octachron commented Sep 10, 2016 •

edited

Loading

gasche commented Feb 17, 2017 •

edited

Loading