Recent

Author Topic: FPDoc XML - TH is a table row?  (Read 2275 times)

dsiders

  • Hero Member
  • *****
  • Posts: 1052
FPDoc XML - TH is a table row?
« on: March 21, 2019, 08:03:10 pm »
Was it intentional that the TH tag in FPDoc XML is a used as table row markup?

I know most of the markup tags generally adhere to the common HTML usage - except for the custom ones used for topic structure. But TH is a definite exception. In HTML it is displayed as a table cell. In FPDoc it is used for a table row.

I know it's documented as being "by design".

Confusing.
Preview Lazarus 3.99 documentation at: https://dsiders.gitlab.io/lazdocsnext

lucamar

  • Hero Member
  • *****
  • Posts: 4219
Re: FPDoc XML - TH is a table row?
« Reply #1 on: March 21, 2019, 08:19:41 pm »
My guess? Whoever "invented" it got confussed and thought <th> was an alternative to <tr> instead of to the correct <td>. It can be seen quite plainly in the doc page for <table>; where it says:
Code: HTML5  [Select][+][-]
  1. <th><td>Value</td><td>Meaning</td></th>
it should be
Code: HTML5  [Select][+][-]
  1. <tr><th>Value</th><th>Meaning</th></tr>
Turbo Pascal 3 CP/M - Amstrad PCW 8256 (512 KB !!!) :P
Lazarus/FPC 2.0.8/3.0.4 & 2.0.12/3.2.0 - 32/64 bits on:
(K|L|X)Ubuntu 12..18, Windows XP, 7, 10 and various DOSes.

valdir.marcos

  • Hero Member
  • *****
  • Posts: 1106
Re: FPDoc XML - TH is a table row?
« Reply #2 on: March 21, 2019, 08:26:54 pm »
Was it intentional that the TH tag in FPDoc XML is a used as table row markup?

I know most of the markup tags generally adhere to the common HTML usage - except for the custom ones used for topic structure. But TH is a definite exception. In HTML it is displayed as a table cell. In FPDoc it is used for a table row.

I know it's documented as being "by design".

Confusing.
My guess? Whoever "invented" it got confussed and thought <th> was an alternative to <tr> instead of to the correct <td>. It can be seen quite plainly in the doc page for <table>; where it says:
Code: HTML5  [Select][+][-]
  1. <th><td>Value</td><td>Meaning</td></th>
it should be
Code: HTML5  [Select][+][-]
  1. <tr><th>Value</th><th>Meaning</th></tr>
Should it be reported as a bug?

lucamar

  • Hero Member
  • *****
  • Posts: 4219
Re: FPDoc XML - TH is a table row?
« Reply #3 on: March 21, 2019, 08:43:53 pm »
Should it be reported as a bug?

It depends on whether it can be considered a bug or just a queer "our-way" gotcha ;D

Fact is nobody said FPDoc XML is HTML; quite the contrary: it most emphatically is not. But the common "HTML-like" tags work like in HTML ... except <th>. So ... is it a bug or is there some reason?

We should see what real HTML is generated from such fpdoc tags: then we would know whether somebody just didn't pay attention to detail or there is a profound reason we don't know about.
Turbo Pascal 3 CP/M - Amstrad PCW 8256 (512 KB !!!) :P
Lazarus/FPC 2.0.8/3.0.4 & 2.0.12/3.2.0 - 32/64 bits on:
(K|L|X)Ubuntu 12..18, Windows XP, 7, 10 and various DOSes.

dsiders

  • Hero Member
  • *****
  • Posts: 1052
Re: FPDoc XML - TH is a table row?
« Reply #4 on: March 21, 2019, 10:22:54 pm »
Should it be reported as a bug?

It depends on whether it can be considered a bug or just a queer "our-way" gotcha ;D

Fact is nobody said FPDoc XML is HTML; quite the contrary: it most emphatically is not. But the common "HTML-like" tags work like in HTML ... except <th>. So ... is it a bug or is there some reason?

We should see what real HTML is generated from such fpdoc tags: then we would know whether somebody just didn't pay attention to detail or there is a profound reason we don't know about.

I never claimed it was HTML. They needed formatting tags for their XML, and smartly decided to re-use the common HTML conventions. They didn't get all crazy like DocBook or DITA. I appreciate that.

But this one exception has to be translated back to the common HTML convention for both HTML and CHM output. And it's being converted in the HTML writer fpdoc/dw_html.pp. Even dwriter.pp (the base writer class) handles it as a row-level element.

My question remains "was it by design"? It's little inconsistencies like this that drive me nuts. ;)

It's not like its a huge issue.15 total files in both FPC Docs and Lazarus use the TH tag. It wouldn't be very difficult to fix it in the XML source if it wasn't by design.

I was just curious.
« Last Edit: March 21, 2019, 10:55:17 pm by dsiders »
Preview Lazarus 3.99 documentation at: https://dsiders.gitlab.io/lazdocsnext

wp

  • Hero Member
  • *****
  • Posts: 11858
Re: FPDoc XML - TH is a table row?
« Reply #5 on: March 21, 2019, 11:43:27 pm »
Could you post this question on the Lazarus mailing list? I think the developers of the xml doc do not read the forum.

dsiders

  • Hero Member
  • *****
  • Posts: 1052
Re: FPDoc XML - TH is a table row?
« Reply #6 on: March 22, 2019, 12:39:06 am »
Could you post this question on the Lazarus mailing list? I think the developers of the xml doc do not read the forum.

Lazarus or FreePascal mailing list? FPDoc is a FPC project.
Preview Lazarus 3.99 documentation at: https://dsiders.gitlab.io/lazdocsnext

wp

  • Hero Member
  • *****
  • Posts: 11858
Re: FPDoc XML - TH is a table row?
« Reply #7 on: March 22, 2019, 12:55:54 am »
Yes, FPC mailing probably is better, I was thinking of the LazDocEditor (lazde). Michael Van Canneyt reads both mailing lists, I think he's the author of the xml doc system.

dsiders

  • Hero Member
  • *****
  • Posts: 1052
Re: FPDoc XML - TH is a table row?
« Reply #8 on: March 22, 2019, 01:10:18 am »
Yes, FPC mailing probably is better, I was thinking of the LazDocEditor (lazde). Michael Van Canneyt reads both mailing lists, I think he's the author of the xml doc system.

I posted to FPC-devel mailing list. I guess its moderated since it didn't appear immediately. We'll see.
Preview Lazarus 3.99 documentation at: https://dsiders.gitlab.io/lazdocsnext

 

TinyPortal © 2005-2018