Consider de-deprecating @visual

31 views
Skip to first unread message

Steven Clontz

unread,
Jun 29, 2022, 11:25:19 AM6/29/22
to PreTeXt development
I've held off on fixing the deprecations given by https://pretextbook.org/doc/guide/html/overview-url.html for all my urls without @visual. I agree that for print formats, a footnote with the spelled-out URL should be provided. However, it's unclear to me that my readers are getting non-neglibible benefit from me manually taking each link, copy-pasting href to visual, and ripping off its https://. More importantly, it's another obnoxious extra step for novice authors without any obvious benefit.

Is there an openness to de-deprecating the required @visual attribute? If possible, maybe we could even process hrefs in XSL to remove http[s]://, which is probably the most common workflow.

Mitch Keller

unread,
Jun 29, 2022, 11:37:41 AM6/29/22
to prete...@googlegroups.com
Although it was a giant pain for me to go through ACS and deal with all of these, I honestly think it’s for the best. As the guide says, dumping a URL into the text of a paragraph (even if it’s a shortened one) is ugly. ACS was written for LaTeX, and so in a lot of places Matt had URLs but had put them through the GVSU URL shortener, making them not ugly. However, in HTML, there is zero justification for showing that URL in the text as the clickable. It is a better practice to make the clickable be part of the sentence text unless it’s absolutely necessary to show the URL. If you want to show the URL without needing @visual, then use <url href=“https://cocalc.com” /> and you will pass validation. Per schema, you only *need* visual if your url element is nonempty.

> On Jun 29, 2022, at 10:25 AM, Steven Clontz <steven...@gmail.com> wrote:
>
> I've held off on fixing the deprecations given by https://pretextbook.org/doc/guide/html/overview-url.html for all my urls without @visual. I agree that for print formats, a footnote with the spelled-out URL should be provided. However, it's unclear to me that my readers are getting non-neglibible benefit from me manually taking each link, copy-pasting href to visual, and ripping off its https://. More importantly, it's another obnoxious extra step for novice authors without any obvious benefit.
>
> Is there an openness to de-deprecating the required @visual attribute? If possible, maybe we could even process hrefs in XSL to remove http[s]://, which is probably the most common workflow.
>
> --
> You received this message because you are subscribed to the Google Groups "PreTeXt development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-dev/3307be71-c75c-4883-8cc7-6930f5fe4675n%40googlegroups.com.

--
Mitch Keller
mi...@rellek.net

http://www.rellek.net/

Steven Clontz

unread,
Jun 29, 2022, 11:42:56 AM6/29/22
to PreTeXt development
Mitch I don't think you addressed my concern: there's no reason that when @visual is missing that @href cannot be used in its place, or even better, @href with any leading `http[s]://` string removed. If someone like myself who's bought-in to PreTeXt already finds this obnoxious, I can guarantee it's bad for attracting new authors.

Steven Clontz

unread,
Jun 29, 2022, 11:45:16 AM6/29/22
to PreTeXt development
Furthermore, it breaks DRY - it's quite possible that through human error, a visual attribute is not equivalent to its href. We should be automating this, not adding more work on authors.

Mitch Keller

unread,
Jun 29, 2022, 11:54:34 AM6/29/22
to prete...@googlegroups.com
I think we only find this obnoxious because we have a lot of things to fix. A new author is going to put in their first url with content and without @visual and get a deprecation warning. They’re pointed toward a resource on how to best handle these things. They will then write things thoughtfully from then on.

> Furthermore, it breaks DRY - it's quite possible that through human error, a visual attribute is not equivalent to its href. We should be automating this, not adding more work on authors.

I disagree about automating. Here’s a for instance of where this warning was legitimately useful in making Matt and me think about how to do things better: The “(Instructors|Students) Read This!” prefaces in ACS point to the YouTube playlists that go with the book. Pretty much all of the other links were added in the original authoring, so Matt had used the GVSU URL shortener and we had nice short links. These YouTube links were *massive*, and automagically getting that dumped out as the visual was *not* good. So realizing what was happening there, I asked Matt to run them through the URL shortener. I left the @href set to the YouTube.com URL, but the @visual is now something like gvsu.edu/s/blah. Honestly, this should probably be part of the best practice…URL shorteners come and go, so you’d hate to have the @href become unreachable and then you might no clue what the link was meant to point to.

I would advocate that keeping the behavior of copying @href into @visual (ideally with the protocol stripped off) but still considering it invalid and issuing a deprecation warning. Then folks get something useful as output, but they also get pointed to a best practice on how to do things well.
> To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-dev/e4ae3ff4-b0bf-4f0d-bc2e-90e7479b6474n%40googlegroups.com.

Steven Clontz

unread,
Jun 29, 2022, 12:01:39 PM6/29/22
to prete...@googlegroups.com
I think automating the url shortening is the real answer here. Who's up for making link.pretextbook.org/foobar work? The fact that you and Matt have a URL shortener you own is an exception, and without a free/open shortener we're back to duplicating info from href to visual, or making authors invest time into shortening their URLs using a proprietary service.

Rob Beezer

unread,
Jun 29, 2022, 12:15:07 PM6/29/22
to prete...@googlegroups.com
I sometimes, but not frequently, do more than just rip off "http[s]://".
Usually just a TLD when the actual URL seems to be an unreliable mess.

So if I thought it could have been automated, I would have done it.

Many things we do intended to promote high-quality source, for conversion to
many formats, some not imagined yet. At first, they might look like make-work.

Rob

Steven Clontz

unread,
Jun 29, 2022, 12:31:10 PM6/29/22
to prete...@googlegroups.com
A huge part in encouraging high quality source is communicating to authors why some tedious human tasks are necessary (descriptions in images), and automating what we can. The more busy work and gotchas you give new authors, the less likely they will adopt PreTeXt. I'm still unconvinced there's a compelling argument as to why stripping the protocol isn't good enough to not need visual required in the schema, and if you ever actually obsolete it you'll just end up with folks not upgrading, or just stripping the protocol by hand anyway.

You received this message because you are subscribed to a topic in the Google Groups "PreTeXt development" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/pretext-dev/n3P-AV9Hgz8/unsubscribe.
To unsubscribe from this group and all its topics, send an email to pretext-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-dev/8bc29784-60ff-7989-6666-003be7a3ee28%40ups.edu.

arech...@gmail.com

unread,
Jun 29, 2022, 12:39:24 PM6/29/22
to PreTeXt development
I agree with Steven = on first use of url it seems strange / confusing that the author has to effectively put in the href twice.  I've just been through my sources fixing this up and by the 10th url I was getting kinda tired. The system should **just** do it for me.

"Just" of course, hides many sins - and I completely understand why this is not completely automagical.

 My $0.02 = if user specifies "visual" then pretext uses that, and otherwise it automagically (powered by unicorns) strips off any leading http(s) stuff and uses that.

Rob Beezer

unread,
Jun 29, 2022, 12:48:30 PM6/29/22
to prete...@googlegroups.com
On 6/29/22 09:39, arech...@gmail.com wrote:
>  My $0.02 = if user specifies "visual" then pretext uses that, and otherwise it
> automagically (powered by unicorns) strips off any leading http(s) stuff and
> uses that.

Pull request welcome. Be sure to get the messages, the deprecation, and the
pre-processor all sorted out.

Rob Beezer

unread,
Jun 29, 2022, 12:50:13 PM6/29/22
to prete...@googlegroups.com
On 6/29/22 09:48, Rob Beezer wrote:
> Be sure to get the messages, the deprecation, and the
> pre-processor all sorted out.

And get documentation sorted. ;-)

Steven Clontz

unread,
Jun 29, 2022, 1:00:01 PM6/29/22
to PreTeXt development
I'll look into such a contribution later this summer. Gotta keep my author/editor hat on for a few days to release some materials in time for the fall....

arech...@gmail.com

unread,
Jun 29, 2022, 2:30:42 PM6/29/22
to PreTeXt development
Rob - you make it sound easy.... now someone just has to code it up. <sarcasm> how hard could it be?</sarcasm>

Rob Beezer

unread,
Jun 29, 2022, 2:37:32 PM6/29/22
to prete...@googlegroups.com
Easy-peasy. The pre-processor is sort of fun. No harder than all-day-yesterday
on ppyyppuutteer. The hard part is some sort of backward compatibility. Not
sure how many time we have de-deprecated something. Is that even a word? I'm
not playing Scrabble with Steven.

I'm off trying to expand access to interactive exercise types, or I'd ....

On 6/29/22 11:30, arech...@gmail.com wrote:
> Rob - you make it sound easy.... now someone just has to code it up. <sarcasm>
> how hard could it be?</sarcasm>
>
> --
> You received this message because you are subscribed to the Google Groups
> "PreTeXt development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email
> to pretext-dev...@googlegroups.com
> <mailto:pretext-dev...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/pretext-dev/a5a98ccf-734c-4574-828a-d78bfb55da0cn%40googlegroups.com
> <https://groups.google.com/d/msgid/pretext-dev/a5a98ccf-734c-4574-828a-d78bfb55da0cn%40googlegroups.com?utm_medium=email&utm_source=footer>.

Rob Beezer

unread,
Jul 2, 2022, 8:13:41 PM7/2/22
to prete...@googlegroups.com
I've de-deprecated this. No more warning message, and default visual/footnote
URL for the with-content case is mildly edited to remove common protocols.

I wish I hadn't edited all of those in the documentation by hand already.

Steven Clontz

unread,
Jul 11, 2022, 10:28:50 AM7/11/22
to prete...@googlegroups.com
Thanks for this Rob! I think this revert will make a lot of new authors' experiences less confusing.
To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-dev/cafdcb6c-890d-3114-e6f8-5638853400aa%40ups.edu.
Reply all
Reply to author
Forward
0 new messages