Thank you so much for making this list! I went through each one and looked
at the documentation for the related @-commands, and with the exception of
sectioning commands and possibly @title I think they are all safe because
the documentation makes it clear that the value will be used in a place
where HTML markup is not allowed. The sectioning commands (and @title) are
different because the documentation doesn't make it clear that the output
might end up somewhere where HTML markup is not permitted and, more
importantly, the obvious output is somewhere where HTML markup is allowed,
commonly used, and helpful.
Changing the documentation is one solution, but it would be even better if
authors could include raw html in these instances. I am a texinfo newbie,
so I apologize if I missing something, but the two possible solutions that
come to my mind are:
1. Use the value from @node or @nodedescription as appropriate instead of
content from sectioning commands. Are there instances where this
substitution wouldn't work? No author is going to need raw formatters in
node names, and I think most authors could do without them in
@nodedescription as well.
2. Provide additional optional commands to provide "safe" values for
section headings. This might look like:
@node I Heart New York
@chapter I <image src="../heart.png"> New York
@chapterplaintext I Heart New York
I prefer #1, and feel confident that it work with the output options I have
used, but I don't know enough to be sure there aren't cases where we would
need an attribute value that currently comes from a section command and a
suitable value from @node or @nodedescription might note be available.
Thank you for your consideration!
Benjamin Kalish
p.s. I am intrigued by "Very motivated users could use the HTML formatting
API to modify the formatting", though I my level of motivation has not yet
been tested! My current workaround for my formatting woes has been to set
variable values at the command line on a per format basis and test for them
using @ifset, but if there is an easier or more idiomatic way of handling
this I would be very happy to learn about it.
On Thu, Sep 26, 2024 at 2:41 AM Patrice Dumas <pertu...@free.fr> wrote:
> On Wed, Sep 25, 2024 at 07:43:10PM -0400, Benjamin Kalish wrote:
> > Thanks. I can see it both ways, but still lean towards it being a bug.
> > Headings in HTML can contain HTML and I don't think the user has any
> reason
> > to expect that the content of a heading would end up anywhere else. If it
> > were up to me the deciding factor would be whether the literal content of
> > the headings need to show up in HTML attributes (and I don't see why they
> > would).
>
> I had a look at the code, I could have missed some places. Attributes
> are based on Texinfo code at least in the following cases (the precise
> @-command being used possibly depending on split/unsplit or other
> customization):
>
> * @image <img> alt attribute
> * <abbr> title attribute based on @abbr/@acronym second argument
> * icon direction formatting <img> alt (based on @node or sectioning
> commands)
> * <meta> name="description" (based on @documentdescription or @*title and
> @node
> or sectioning commands).
> * <meta> name="keywords" (based on @*title and @node or sectioning
> commands).
> * <link> title attribute (based on @node or sectioning commands).
> * (button name or description as title or rel in href or link elements,
> but this can be ignored here as it is not based on user Texinfo code)
>
> I did not list the places where a file is expected (@image first
> argument, @verbatiminclude), but we can assume that users do not get the
> idea
> to use @inlineraw in those contexts.
>
> > If it is necessary, then yes, it is up to the user to avoid the use
> > of @inlineraw headings (and a warning would be most welcome!).
>
> @inlineraw with entities but no element is ok too, so a warning may be
> unnecessary.
>
> > On the other
> > hand, if it is not necessary and that content doesn't need to show up in
> > attributes, or if an escaped version could be used instead,
>
> I can't imagine any other change than removing the alt/title/metadata
> output (as described above). This is possible, as none of these
> attributes are strictly needed, yet the produced HTML is better with
> those, I think. Very motivated users could use the HTML formatting API
> to modify the formatting.
>
> Also note that this issue could happen for other formats, for instance
> in DocBook there could be similar issues with attributes. In LaTeX
> output, the commands that can end up in captions or table of contents
> cannot contain everything.
>
> > then the user
> > should be allowed to use @inlineraw here and a change to the code is
> > necessary to prevent noncompliant HTML output.
>
> It is difficult or even impossible to avoid noncompliant HTML output when
> raw HTML is output. There is this issue of expansion of raw HTML in
> attributes, but it is probably only one possible issue amng many others.
> How HTML generated from Texinfo code and raw HTML interact cannot be
> foreseen when parsing or outputting because HTML in raw HTML is not
> analysed (Texinfo in raw HTML is parsed as usual) but simply output
> unchanged.
>
>
> What about the following sentence in "Inline Conditionals: ‘@inline’,
> ‘@inlineifelse’, ‘@inlineraw’" node?
>
> Beware that in some command arguments, such as @node or sectioning
> commands raw @inlineraw text is output in diverse formatting contexts.
> Raw HTML could end up in HTML attributes, raw LaTeX could be used for
> table of contents. You should make sure that the raw code you provide
> is adequate in such contexts.
>
> --
> Pat
Benjamin Kalish
Cataloger / Technology Librarian
Forbes Library Technical Services
bkal...@forbeslibrary.org
413-587-1011
Support Forbes Library:
- Consider giving a gift
<https://forbeslibrary.org/giving/donate-online/> to Forbes Library
- Vote for the Friends of Forbes in the Florence Bank Community Grant
Program <https://www.florencebank.com/vote>.
- Join the Friends of Forbes today <https://forbeslibrary.org/friends/>!
Currently reading: *Jumpnauts* by Hao Jingfang
Just Finished: *Children of Memory* by Adrian Tchaikovsky
For information about accessibility at the library, please see:
http://forbeslibrary.org/accessibility/
On Thu, Sep 26, 2024 at 2:41 AM Patrice Dumas <pertu...@free.fr> wrote:
> On Wed, Sep 25, 2024 at 07:43:10PM -0400, Benjamin Kalish wrote:
> > Thanks. I can see it both ways, but still lean towards it being a bug.
> > Headings in HTML can contain HTML and I don't think the user has any
> reason
> > to expect that the content of a heading would end up anywhere else. If it
> > were up to me the deciding factor would be whether the literal content of
> > the headings need to show up in HTML attributes (and I don't see why they
> > would).
>
> I had a look at the code, I could have missed some places. Attributes
> are based on Texinfo code at least in the following cases (the precise
> @-command being used possibly depending on split/unsplit or other
> customization):
>
> * @image <img> alt attribute
> * <abbr> title attribute based on @abbr/@acronym second argument
> * icon direction formatting <img> alt (based on @node or sectioning
> commands)
> * <meta> name="description" (based on @documentdescription or @*title and
> @node
> or sectioning commands).
> * <meta> name="keywords" (based on @*title and @node or sectioning
> commands).
> * <link> title attribute (based on @node or sectioning commands).
> * (button name or description as title or rel in href or link elements,
> but this can be ignored here as it is not based on user Texinfo code)
>
> I did not list the places where a file is expected (@image first
> argument, @verbatiminclude), but we can assume that users do not get the
> idea
> to use @inlineraw in those contexts.
>
> > If it is necessary, then yes, it is up to the user to avoid the use
> > of @inlineraw headings (and a warning would be most welcome!).
>
> @inlineraw with entities but no element is ok too, so a warning may be
> unnecessary.
>
> > On the other
> > hand, if it is not necessary and that content doesn't need to show up in
> > attributes, or if an escaped version could be used instead,
>
> I can't imagine any other change than removing the alt/title/metadata
> output (as described above). This is possible, as none of these
> attributes are strictly needed, yet the produced HTML is better with
> those, I think. Very motivated users could use the HTML formatting API
> to modify the formatting.
>
> Also note that this issue could happen for other formats, for instance
> in DocBook there could be similar issues with attributes. In LaTeX
> output, the commands that can end up in captions or table of contents
> cannot contain everything.
>
> > then the user
> > should be allowed to use @inlineraw here and a change to the code is
> > necessary to prevent noncompliant HTML output.
>
> It is difficult or even impossible to avoid noncompliant HTML output when
> raw HTML is output. There is this issue of expansion of raw HTML in
> attributes, but it is probably only one possible issue amng many others.
> How HTML generated from Texinfo code and raw HTML interact cannot be
> foreseen when parsing or outputting because HTML in raw HTML is not
> analysed (Texinfo in raw HTML is parsed as usual) but simply output
> unchanged.
>
>
> What about the following sentence in "Inline Conditionals: ‘@inline’,
> ‘@inlineifelse’, ‘@inlineraw’" node?
>
> Beware that in some command arguments, such as @node or sectioning
> commands raw @inlineraw text is output in diverse formatting contexts.
> Raw HTML could end up in HTML attributes, raw LaTeX could be used for
> table of contents. You should make sure that the raw code you provide
> is adequate in such contexts.
>
> --
> Pat
>
