Embedded Format Codes in Definitions

[finanalyst]

@thoughtstream @lizmat tl;dr Can a =defn have format codes embedded in the term term?

format code is a markup code without side-effects.

I am implementing =defn and =numdefn and run across a limitation I think is not natural. (RakuDoc v1 using $=pod did not implement =defn well)

At a minimum, we have

=defn A term
The expansion

At the present, we can have embedded format codes in the expansion but not in the term, that is:

=defn A term
The expansion may have U<embedded> format codes at present.

Currently we cannot have

=defn A term with B<embedded> format codes
The expansion with or without format codes

@thoughtstream was it intended that the term should be without format codes?

@lizmat would it be possible to have numdefn have the same AST as defn? Currently, numdefn is treated as a normal block, meaning that a series of tests on the Paragraph elements needs to be run to determine what is in the term and what is in the expansion.

FYI I propose that for =alias TERM EXPANSION TERM is most definitely without format codes!

@lizmat I propose that even if the term and expansion parts are Str, the AST for a defn & numdefn is

RakuAST::Doc::Block.new(
  type        => "defn",
  abbreviated => True,
  paragraphs  => (
    RakuAST::Doc::Paragraph.new( ... )
    RakuAST::Doc::Paragraph.new( ... )
   )
...

[lizmat]

On 29 May 2024, at 12:59, Richard Hainsworth @.***> wrote: @thoughtstream was it intended that the term should be without format codes?

FWIW, that's how it is explicitely implemented at the moment

@lizmat would it be possible to have numdefn have the same AST as defn? Currently, numdefn is treated as a normal block, meaning that a series of tests on the Paragraph elements needs to be run to determine what is in the term and what is in the expansion.

https://github.com/rakudo/rakudo/commit/042660d8dc does this

FYI I propose that for =alias TERM EXPANSION TERM is most definitely without format codes! @lizmat I propose that even if the term and expansion parts are Str, the AST for a defn & numdefn is RakuAST::Doc::Block.new( type => "defn", abbreviated => True, paragraphs => ( RakuAST::Doc::Paragraph.new( ... ) RakuAST::Doc::Paragraph.new( ... ) )

I don't see the point of that: the first element in "paragraphs" is always the lemma, regardless of whether that is another paragraph or a string. And the second element is the body, also regardless of whether it is a Paragraph object or a string.

Again: the advantage of strings in this context, is that you can be sure that you don't need to do any format processing!

[thoughtstream]

My expectation was that the "term" component of a =defn should not have formatting.

I can see why formatting might be useful within a term, and it may seem odd to end-users that it's one of the few places where you can write ordinary text, but can't use formatting codes. However, the term component also acts as a target for L<defn:...> links, and it would seem better if that target is unambiguous.

I mean, if we allow:

    =defn A term with B<embedded> formatting codes
    The definition with or without formatting codes

...then does the corresponding L<defn:...> also have to be: L<defn:"A term with B<embedded> formatting codes>"?

It seems simpler (at least initially) just to specify that the term of a =defn is treated as a if it were a V<> literal string, with any apparent formatting codes ignored (and perhaps warned about). The same rule should probably also apply to the term component of an inline D<>.

Besides, the idea was that the term component automatically gets special formatting anyway. That is:

    =defn A term
    The definition with or without formatting codes

    A D<placement directive> inserts something into the document at that point.

...should be rendered in such a way that the term is easily distinguished as the thing being defined. Something like:

   A term       The definition with or without formatting codes

   A placement directive inserts something into the document at that point.

So the TL;DR is: No, I didn't intend the term component of a =defn to allow formatting codes. But, as always, I'm happy to discuss the issue further.

[finanalyst]

@thoughtstream & @lizmat That's the way =defn / D<> are implemented. Closing as resolved. I'll add a clarification as suggested

[finanalyst]

closing as resolved