update author guide for visual attribute

[kcrisman]

https://pretextbook.org/doc/guide/html/topic-url.html still says

Compare <url href="https://example.com/">Demo Site</url>(https://pretextbook.org/doc/guide/html/topic-url.html#p-763)which will render ...

but pretext-announce says that the visual is now mandatory, and I get plenty of

error: text not allowed here; expected the element end-tag

because of this. I presume the Author guide should explicitly disallow those, correct?

[rbeezer]

I think the Guide is correct. Nobody wanted to be bothered with @visual in trivial cases, so we automated a (little bit) of URL clean-up and left it at that.

Your error is coming from the schema, no? (You don't say.)

We just need to relax the @visual attribute to be optional? Is that right? I don't know just what all this URL/href/footnote stuff gets me so twisted up... ;-)

[kcrisman]

Oh! I thought that the warnings in the schema were because of deprecation - see the pretext-announce link above:

You will get warnings for the deprecated version... [b]ut they will continue to behave acceptably, as you will get @href in a footnote. For now.

So I figured that these would eventually need to be fully replaced, and the guide should be updated. However, I greatly prefer the auto-URLs that you generate to that! There are a few (e.g. from StackExchange sites) I'll probably still edit by hand, but even though

my deprecation-pain is always greater than yours

I'd still be grateful for that, and I think new authors would be as well for not having to (essentially) duplicate a ton of URLs in their source.

Anyway, as to the technical solution: It currently has

            Url =
                element url {
                    attribute href {text},
                    (
                        (attribute visual {text},
                        TextShort
                        )|(
                        attribute visual {text}?
                        )
                    )
                }

The visual attribute is already optional, but what isn't an option is having no visual, but having any content.

Now, there is also the "experimental" xml for the rng:

Specifically, changes to Url, that only recommend a visual element when the URL element contains content.

            Url |=
                element url {
                    attribute href {text},
                    (
                        (attribute visual {text},
                        TextShort
                        )| TextShort |
                        (
                        attribute visual {text}?
                        )
                    )
                }

This removes all of those validation problems, and the options look correct. Probably it could be even shorter with just

            Url |=
                element url {
                    attribute href {text},
                    (
                        (attribute visual {text}?,
                        TextShort?
                        )
                    )
                }

But maybe that is too "relaxed". Which solution do you think is best?

[kcrisman]

Ping @rbeezer as probably helpful for workshop (so that authors validating their new document types don't get scared) - I'm happy to implement any of the above solutions.

[oscarlevin]

We have just spent a couple hours working on the schema and will propose your shortened version of the experimental schema, but as the official version.

[kcrisman]

We have just spent a couple hours working on the schema and will propose your shortened version of the experimental schema, but as the official version.

Awesome, glad that makes sense.

[rbeezer]

Closed by a414e3dd471fe3878ec00203691740cefa071ad1 as part of #2211