Conversation
following what was recommended during the RFC for 2.1 by msdemlei Fixes ivoa-std#93
4af0b73 to
e7fe6c3
Compare
I replaced \item[Arguments]: -> \item[Arguments:] throughout the changes; the existing formulation put the colons in a funny place in the HTML output.
mbtaylor
left a comment
mbtaylor
left a comment
There was a problem hiding this comment.
I'm not sure that this is more readable than the previous table-based formatting, but it doesn't look wrong.
|
I do not know either if it is more readable. The table version was OK according to me because more compact and still readable. |
|
However, about your commit @mbtaylor , it is "quite" OK for the HTML, but not anymore in the PDF. I put the semi-colon outside the And anyway, even with the semi-colon inside, the rendering is not that great in the HTML version. I guess one should fix the CSS for the HTML version so that definition lists look much better than that. @msdemlei , is it OK if I propose few CSS lines to fix the rendering in HTML? Should it be in ivoatex or somewhere else (I see that styles are coming from here: https://www.ivoa.net/misc/ivoa_doc.css)? |
|
An alternative would be to format the list of functions differently. Before this version, I tried with only definition lists but multiple level of such lists is apparently badly converted from tex to pdf. I also tried with only standard lists, but I did not like the rendering. If anyone has a better idea, I can try it. |
|
Sorry about that, I added some |
|
On Tue, Aug 25, 2026 at 09:36:29AM +0000, Grégory Mantelet wrote:
gmantele left a comment (ivoa-std/ADQL#107)
And anyway, even with the semi-colon inside, the rendering is not
that great in the HTML version. I guess one should fix the CSS for
the HTML version so that definition lists look much better than
that. @msdemlei , is it OK if I propose few CSS lines to fix the
rendering in HTML? Should it be in ivoatex or somewhere else (I see
that styles are coming from here:
https://www.ivoa.net/misc/ivoa_doc.css)?
ivoa_doc.css is not under ivoatex's control, but thankfully it's not
at least under version control: https://github.com/ivoa/ivoa-web,
./current-html/misc/ivoa_doc.css.
Better table rendering is certainly a good thing, so +1 from me. I'm
not sure who gets to review this right now. If you do a PR, that'll
be a good excuse for me to pester the exec about quicker ivoa-web
reviews.
|
@msdemlei , what did you mean? You mean that finally, you prefer having a table to list and describe functions? |
|
On Thu, Sep 24, 2026 at 12:53:26AM -0700, Grégory Mantelet wrote:
gmantele left a comment (ivoa-std/ADQL#107)
> Better table rendering is certainly a good thing, so +1 from me. I'm not sure who gets to review this right now.
@msdemlei , what did you mean? You mean that finally, you prefer having a table to list and describe functions?
Oh, no, sorry. While it's true that touches to the default table CSS
of ivoa_doc.css would be cool, too, the main point of my comment is:
Just make a PR against ivoa_doc.css on ivoa-web (tables or lists or
whatever) and I'll see to it that it'll be reviewed.
|
The text "|\textit{r}| is less than |\textit{y}|" rendered OK
in the PDF, but in the HTML came out as the incomprehensible/wrong
"- r - is less than - y -".
This is not new, it was in ADQL 2.1 as well, but might as well
fix it here.
mbtaylor
left a comment
mbtaylor
left a comment
There was a problem hiding this comment.
Definite improvement on the previous version, this one looks OK by me. Not convinced it's better than the original table layout, but happy to approve (with small legacy fix that I made).
Thanks for the fix, @mbtaylor |
|
On Fri, Sep 25, 2026 at 06:34:26AM -0700, Grégory Mantelet wrote:
gmantele left a comment (ivoa-std/ADQL#107)
Here is another way to represent these functions. This time,
according to be, it is both more compact and more readable. What do
you think @msdemlei @mbtaylor ?
I like it better than the table, and it's much easier to grow, too.
But: why not use the signature directly as the defined term in the
description? So, rather than
\item[\texttt{abs(x)}]
\texttt{double abs(double x)} \\
Returns the absolute value of x.
simply write:
\item[\texttt{double abs(double x)}]
Returns the absolute value of x.
I don't think there will be any signatures that are too long for
definition labels.
While you are at it, *perhaps* we can move to TAPRegExt-style
signatures -- as in abs(x DOUBLE) -> DOUBLE (or perhaps even \to
rather than ->). But that's not a strong desire on my end.
|
This branch has not been deployed
3 participants
Following the recommendation by @msdemlei during the RFC for 2.1, the tables for math and trigo functions have been converted into lists. A sub-sub-section has been added to clearly split the two lists.
Fixes #93