Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature request: Modern and clean HTML5 output #8738

Open
milasudril opened this issue Aug 28, 2021 · 9 comments
Open

Feature request: Modern and clean HTML5 output #8738

milasudril opened this issue Aug 28, 2021 · 9 comments
Labels
enhancement a request to enhance doxygen, not a bug needinfo reported bug is incomplete, please add additional info

Comments

@milasudril
Copy link

Describe the bug
I would like to have an output mode that produces clean HTML5, with less divs and tables. In particular, current doxygen still uses tables as layout elements. Also, empty table rows are used for layout purposes. This should be done with css

Expected behavior
Clean HTML5. Use semantic elements like nav and menu instead of a div soup. Also, remove the requirement that the header bar is 56 pixels high. This issue should be possible to solve with modern CSS.

@albert-github albert-github added enhancement a request to enhance doxygen, not a bug needinfo reported bug is incomplete, please add additional info labels Aug 28, 2021
@albert-github
Copy link
Collaborator

  • Which version of doxygen are you using?
  • Where did you see "Also, empty table rows are used for layout purposes. "
    • Can you please attach a, small, self contained example (source+configuration file in a tar or zip) that allows us to reproduce the problem? Please don't add external links as they might not be persistent.
  • Where did you see "Also, remove the requirement that the header bar is 56 pixels high. "
    • Can you please attach a, small, self contained example (source+configuration file in a tar or zip) that allows us to reproduce the problem? Please don't add external links as they might not be persistent.

@milasudril
Copy link
Author

milasudril commented Aug 29, 2021

This "problem" is always reproducible on any version of doxygen except perhaps very old ones which may target HTML 3. You can verify these claims by using web developer tools in your browser. It appears that 56 px limit (documented in the in the configuration file template is forced by a script. I haven't digged into the details, but I guess it has to do with computation of box heights. These problems should disappear if the output used modern CSS, in combination with cleaner HTML.

@doxygen
Copy link
Owner

doxygen commented Aug 29, 2021

@milasudril Next to giving some concrete examples of what is wrong in your view, you also forgot to mention why you would need these changes. I could also say: "the code should use C++20 features", but without mentioning why, it just a "new is better" type of remark, whereas doxygen typically needs to be a bit conservative to also support older compilers (or browsers in your case)...

@milasudril
Copy link
Author

It is maybe not new is better. Rather "old is bad". Anyway, some benefits include:

  • Easier to apply custom CSS stylesheets, and probably more robust too, since the styling API since many of the special id:s or css class names are no longer necessary. Simply apply the style to the corresponding semantic element.
  • Smaller HTML files
  • Better for search engines
  • Possibly faster interaction with the webpage (less dependent on scripts)
  • Better portability across browsers and devices (excluding IE, but who needs it)

Also "Latest and Greatest" in this context is context is not very new either. It should be sufficient with a 5 or 6 year old browser. Old browsers is a non-issue, because no one should use older browsers anyway (for different reasons than new functionality).

One could still use the xml output, but I think that is also not a good idea because it requires extra maintenance of local scripts that convert the xml into HTML. These may need updates when doxygen changes.

albert-github added a commit to albert-github/doxygen that referenced this issue Aug 29, 2021
In respect to the project area of the doxygen HTML output a number of items were coded with `style=` in the , user changeable, `header.html` and others were coded through settings in the, user changeable, `doxygen.css`.
This has been made consistent so all runs through the css.
@albert-github
Copy link
Collaborator

albert-github commented Aug 29, 2021

After some searching in respect to the "56px" problem I found some inconsistencies:

In respect to the "empty table rows are used for layout purposes" I couldn't find an example, doxygen uses quite a few tables, so for this still the request remains:

  • Can you please attach a, small, self contained example (source+configuration file in a tar or zip) that allows us to reproduce the problem? Please don't add external links as they might not be persistent.
  • Please also specify the full doxygen version used (doxygen -v).

@milasudril
Copy link
Author

milasudril commented Aug 29, 2021

<tr class="separator:...">

is the empty row I am talking about.

<table class="memberdecls">
<tbody><tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-methods" name="pub-methods"></a>
Public Member Functions</h2></td></tr>
<tr class="memitem:ad3900660601d56204abc5da7d8e3e70f"><td class="memItemLeft" valign="top" align="right">&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classfruit_1_1_line_layout.html#ad3900660601d56204abc5da7d8e3e70f">LineLayout</a> (<a class="el" href="classfruit_1_1_line_layout.html#a6442516ca55d6b6da53abba7c279e191">Direction</a> dir=<a class="el" href="classfruit_1_1_line_layout.html#a6442516ca55d6b6da53abba7c279e191ad1e80c506f4c89e3c4fb1c1b4867a03c">Direction::LeftToRight</a>)</td></tr>
<tr class="memdesc:ad3900660601d56204abc5da7d8e3e70f"><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Constructs a new <a class="el" href="classfruit_1_1_line_layout.html" title="Positions its member in a straight line.">LineLayout</a>, and sets the direction to dir.  <a href="classfruit_1_1_line_layout.html#ad3900660601d56204abc5da7d8e3e70f">More...</a><br></td></tr>
<tr class="separator:ad3900660601d56204abc5da7d8e3e70f"><td class="memSeparator" colspan="2">&nbsp;</td></tr>
<tr class="memitem:a5bce824ab9780fa14271894996a5e93d"><td class="memItemLeft" valign="top" align="right">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classfruit_1_1_line_layout.html#a5bce824ab9780fa14271894996a5e93d">push_back</a> (<a class="el" href="structfruit_1_1_layout_box.html">LayoutBox</a> const &amp;box)</td></tr>
<tr class="memdesc:a5bce824ab9780fa14271894996a5e93d"><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Places box at the end of the line.  <a href="classfruit_1_1_line_layout.html#a5bce824ab9780fa14271894996a5e93d">More...</a><br></td></tr>
<tr class="separator:a5bce824ab9780fa14271894996a5e93d"><td class="memSeparator" colspan="2">&nbsp;</td></tr>
<tr class="memitem:ab10ce71406065b3363693f4491ddbb29"><td class="memItemLeft" valign="top" align="right"><a class="el" href="structfruit_1_1_size_request_result.html">SizeRequestResult</a>&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classfruit_1_1_line_layout.html#ab10ce71406065b3363693f4491ddbb29">handle</a> (<a class="el" href="structfruit_1_1_size_request_event.html">SizeRequestEvent</a> const &amp;) const</td></tr>
<tr class="memdesc:ab10ce71406065b3363693f4491ddbb29"><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Wrapper function that exists so that a <a class="el" href="classfruit_1_1_line_layout.html" title="Positions its member in a straight line.">LineLayout</a> can respond to <a class="el" href="structfruit_1_1_size_request_event.html">SizeRequestEvents</a>.  <a href="classfruit_1_1_line_layout.html#ab10ce71406065b3363693f4491ddbb29">More...</a><br></td></tr>
<tr class="separator:ab10ce71406065b3363693f4491ddbb29"><td class="memSeparator" colspan="2">&nbsp;</td></tr>
<tr class="memitem:acb3155a9b7915a62a773111cbed9212b"><td class="memItemLeft" valign="top" align="right">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classfruit_1_1_line_layout.html#acb3155a9b7915a62a773111cbed9212b">handle</a> (<a class="el" href="structfruit_1_1_geometry_update_event.html">GeometryUpdateEvent</a> const &amp;event)</td></tr>
<tr class="memdesc:acb3155a9b7915a62a773111cbed9212b"><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Processes <a class="el" href="structfruit_1_1_geometry_update_event.html">GeometryUpdateEvents</a>.  <a href="classfruit_1_1_line_layout.html#acb3155a9b7915a62a773111cbed9212b">More...</a><br></td></tr>
<tr class="separator:acb3155a9b7915a62a773111cbed9212b"><td class="memSeparator" colspan="2">&nbsp;</td></tr>
<tr class="memitem:aa64628da81fc2600a4c91615b25eb81e"><td class="memItemLeft" valign="top" align="right">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classfruit_1_1_line_layout.html#aa64628da81fc2600a4c91615b25eb81e">set_direction</a> (<a class="el" href="classfruit_1_1_line_layout.html#a6442516ca55d6b6da53abba7c279e191">Direction</a> dir)</td></tr>
<tr class="memdesc:aa64628da81fc2600a4c91615b25eb81e"><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Sets the Direction of this <a class="el" href="classfruit_1_1_line_layout.html" title="Positions its member in a straight line.">LineLayout</a>.  <a href="classfruit_1_1_line_layout.html#aa64628da81fc2600a4c91615b25eb81e">More...</a><br></td></tr>
<tr class="separator:aa64628da81fc2600a4c91615b25eb81e"><td class="memSeparator" colspan="2">&nbsp;</td></tr>
<tr class="memitem:a4ce685950a39039c28142fddfb2330f7"><td class="memItemLeft" valign="top" align="right"><a class="el" href="classfruit_1_1_line_layout.html#a6442516ca55d6b6da53abba7c279e191">Direction</a>&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classfruit_1_1_line_layout.html#a4ce685950a39039c28142fddfb2330f7">direction</a> () const</td></tr>
<tr class="memdesc:a4ce685950a39039c28142fddfb2330f7"><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Retrieves the current Direction of this <a class="el" href="classfruit_1_1_line_layout.html" title="Positions its member in a straight line.">LineLayout</a>.  <a href="classfruit_1_1_line_layout.html#a4ce685950a39039c28142fddfb2330f7">More...</a><br></td></tr>
<tr class="separator:a4ce685950a39039c28142fddfb2330f7"><td class="memSeparator" colspan="2">&nbsp;</td></tr>
<tr class="memitem:aa3f88c55ebb138eb0123ef0b09788e37"><td class="memItemLeft" valign="top" align="right">size_t&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classfruit_1_1_line_layout.html#aa3f88c55ebb138eb0123ef0b09788e37">widget_count</a> () const</td></tr>
<tr class="memdesc:aa3f88c55ebb138eb0123ef0b09788e37"><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Retrieves the number of members in this <a class="el" href="classfruit_1_1_line_layout.html" title="Positions its member in a straight line.">LineLayout</a>.  <a href="classfruit_1_1_line_layout.html#aa3f88c55ebb138eb0123ef0b09788e37">More...</a><br></td></tr>
<tr class="separator:aa3f88c55ebb138eb0123ef0b09788e37"><td class="memSeparator" colspan="2">&nbsp;</td></tr>
<tr class="memitem:af7fa4e1f70e540dd8fd8aeb45f4937dd"><td class="memItemLeft" valign="top" align="right">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classfruit_1_1_line_layout.html#af7fa4e1f70e540dd8fd8aeb45f4937dd">set_width</a> (float value)</td></tr>
<tr class="memdesc:af7fa4e1f70e540dd8fd8aeb45f4937dd"><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Sets the width of this <a class="el" href="classfruit_1_1_line_layout.html" title="Positions its member in a straight line.">LineLayout</a>, relative to the size passed to compute_min_size(ViewportSize) const.  <a href="classfruit_1_1_line_layout.html#af7fa4e1f70e540dd8fd8aeb45f4937dd">More...</a><br></td></tr>
<tr class="separator:af7fa4e1f70e540dd8fd8aeb45f4937dd"><td class="memSeparator" colspan="2">&nbsp;</td></tr>
<tr class="memitem:a3f0353a4d39dcbb0f59d0ad38477934b"><td class="memItemLeft" valign="top" align="right">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classfruit_1_1_line_layout.html#a3f0353a4d39dcbb0f59d0ad38477934b">set_width</a> (int value)</td></tr>
<tr class="memdesc:a3f0353a4d39dcbb0f59d0ad38477934b"><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Sets the width in pixels of this <a class="el" href="classfruit_1_1_line_layout.html" title="Positions its member in a straight line.">LineLayout</a>.  <a href="classfruit_1_1_line_layout.html#a3f0353a4d39dcbb0f59d0ad38477934b">More...</a><br></td></tr>
<tr class="separator:a3f0353a4d39dcbb0f59d0ad38477934b"><td class="memSeparator" colspan="2">&nbsp;</td></tr>
<tr class="memitem:a470df4d3132f9070478c078b99e709ee"><td class="memItemLeft" valign="top" align="right">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classfruit_1_1_line_layout.html#a470df4d3132f9070478c078b99e709ee">set_height</a> (float value)</td></tr>
<tr class="memdesc:a470df4d3132f9070478c078b99e709ee"><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Sets the height of this <a class="el" href="classfruit_1_1_line_layout.html" title="Positions its member in a straight line.">LineLayout</a>, relative to the size passed to compute_min_size(ViewportSize) const.  <a href="classfruit_1_1_line_layout.html#a470df4d3132f9070478c078b99e709ee">More...</a><br></td></tr>
<tr class="separator:a470df4d3132f9070478c078b99e709ee"><td class="memSeparator" colspan="2">&nbsp;</td></tr>
<tr class="memitem:a98d621efd14ffef9ebfff716b65f7b7e"><td class="memItemLeft" valign="top" align="right">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classfruit_1_1_line_layout.html#a98d621efd14ffef9ebfff716b65f7b7e">set_height</a> (int value)</td></tr>
<tr class="memdesc:a98d621efd14ffef9ebfff716b65f7b7e"><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Sets the height in pixels of this <a class="el" href="classfruit_1_1_line_layout.html" title="Positions its member in a straight line.">LineLayout</a>.  <a href="classfruit_1_1_line_layout.html#a98d621efd14ffef9ebfff716b65f7b7e">More...</a><br></td></tr>
<tr class="separator:a98d621efd14ffef9ebfff716b65f7b7e"><td class="memSeparator" colspan="2">&nbsp;</td></tr>
<tr class="memitem:ae96f819f9f6387169cb3f8654625e74b"><td class="memItemLeft" valign="top" align="right"><a class="el" href="structfruit_1_1_viewport_size.html">ViewportSize</a>&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classfruit_1_1_line_layout.html#ae96f819f9f6387169cb3f8654625e74b">compute_min_size</a> () const</td></tr>
<tr class="memdesc:ae96f819f9f6387169cb3f8654625e74b"><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Computes the minimum space that this <a class="el" href="classfruit_1_1_line_layout.html" title="Positions its member in a straight line.">LineLayout</a> will require.  <a href="classfruit_1_1_line_layout.html#ae96f819f9f6387169cb3f8654625e74b">More...</a><br></td></tr>
<tr class="separator:ae96f819f9f6387169cb3f8654625e74b"><td class="memSeparator" colspan="2">&nbsp;</td></tr>
<tr class="memitem:aa2a35e4591165af8b4ac28ee126166b3"><td class="memItemLeft" valign="top" align="right"><a class="el" href="classfruit_1_1_elastic_viewport_size.html">ElasticViewportSize</a>&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="classfruit_1_1_line_layout.html#aa2a35e4591165af8b4ac28ee126166b3">min_size</a> () const</td></tr>
<tr class="separator:aa2a35e4591165af8b4ac28ee126166b3"><td class="memSeparator" colspan="2">&nbsp;</td></tr>
</tbody></table>

Other examples of bad markup:

<h2 class="memtitle"><span class="permalink"><a href="#acb3155a9b7915a62a773111cbed9212b">◆&nbsp;</a></span>handle() <span class="overload">[1/2]</span></h2>
<table class="memname">
        <tbody><tr>
          <td class="memname">void fruit::LineLayout::handle </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="structfruit_1_1_geometry_update_event.html">GeometryUpdateEvent</a> const &amp;&nbsp;</td>
          <td class="paramname"><em>event</em></td><td>)</td>
          <td></td>
        </tr>
      </tbody></table>

This should not really be a table. This should be a paragraph, where the "td" tags are replaced with span. Or if you want void fruit::LineLayout::handle, which is an available option in HTML5. The proper output would be

<section class="memberdesc" id="...">
<!-- No need to use a tags for anchors -->
<header>
<h1>void handle()<doxy-overload>[1/2]</doxy-overload></h1>
<p class="memfullname">
  <doxy-rettype>void</doxy-rettype>
  <doxy-memname>fruit::LineLayout::handle</doxy-memname>(
  <doxy-paramtype><a class="el" href="...">GeometryUpdateEvent</a>const &amp;</doxy-paramtype><doxy-paramname>event</dox-paramname>)
</p>
</header>
<!---Description-->
</section>

For the question about version: I think the "new" look appeared for the first time in version 1.7 or maybe it was introduced in 1.8. Anyways, It looks the same in version 1.9.3.

A good benchmark is that the web page should look descent without any scripts or stylesheets enabled.

@albert-github
Copy link
Collaborator

When we look at the "empty" line like:

<tr class="separator:aa2a35e4591165af8b4ac28ee126166b3"><td class="memSeparator" colspan="2">&nbsp;</td></tr>

We see that it has a class: memSeparator
and the definition here is:

.memSeparator {
        border-bottom: 1px solid ##E2;
        line-height: 1px;
        margin: 0px;
        padding: 0px;
}

the intention of this line is to obtain a nice separator line between the different different members.

@milasudril
Copy link
Author

milasudril commented Aug 29, 2021

But that is not needed:

table{border-collapse:collapse; width:calc(100% - 1em); margin-bottom:1ex}
table.memberdecls{border-bottom:3px double}
td.memItemLeft, td.memItemRight{padding-top: 1ex;border-top:1px solid}
td.mdescLeft, td.mdescRight{padding-bottom: 1ex}

doxygen added a commit that referenced this issue Aug 30, 2021
issue #8738 Fixed sizes in project area of HTML output
@albert-github
Copy link
Collaborator

albert-github commented Aug 30, 2021

The proposed patch regarding the fixed size in header.html has been integrated in master on GitHub.

doxygen pushed a commit that referenced this issue Sep 1, 2021
In respect to the project area of the doxygen HTML output a number of items were coded with `style=` in the , user changeable, `header.html` and others were coded through settings in the, user changeable, `doxygen.css`.
This has been made consistent so all runs through the css.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement a request to enhance doxygen, not a bug needinfo reported bug is incomplete, please add additional info
Projects
None yet
Development

No branches or pull requests

3 participants