Sorry for the bad example at the end. I tried too quickly to come up with
something clever. I should have stuck with the example I originally used,
in which case that second possibility would look like:
@node One
@chapter @inlineraw{html,<span class="test">}One@inlineraw{html,</span>}
@chapterplaintext One
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 12:01 PM Benjamin Kalish <bkal...@forbeslibrary.org>
wrote:
> 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
>>
>
