"View Source on GitHub" feature to promote open-source engagement?

[Steven Clontz]

This feature concept came out of a discussion with Chrissy S on engaging instructors as potential open source contributors to books.

If we give authors/publishers a way to provide a canonical GitHub repository link (example:  ) and use the output of mapping.json (example: https://github.com/StevenClontz/intro-to-topology/blob/gh-pages/.mapping.json ) , every HTML page can infer the location of the page's source on GitHub.

Example...

Repo link: https://github.com/StevenClontz/intro-to-topology

mapping.json output: https://github.com/StevenClontz/intro-to-topology/blob/gh-pages/.mapping.json

Now suppose an instructor found a typo in https://stevenclontz.github.io/intro-to-topology/section-metric.html .

We can use the above repo link and mapping.json output to contstruct a direct link to {{repo_link}}/blob/main/{{path_to_xml_id}} that is

https://github.com/StevenClontz/intro-to-topology/blob/main/source/sections/metric.xml

By automatically supplying that link (when an author opts into providing a canonical GitHub repo in source somewhere), we can have a "View PTX Source" button on every page that lets the reader see the (latest version) of the source. If this reader is logged into GitHub, they can click a pencil icon and propose a pull request directly fixing the typo, *without knowing what a pull request is*.

Furthermore it makes the jump from "oh here's a feature in someone's PreTeXt book, how do I do that in mine" much shorter, since they don't have to find documentation or the corresponding example in the annotated sample article.

I'd like to contribute this, but would need guidance on the best implementation. Thoughts?

Very elaborate mockup:

[Rob Beezer]

David Farmer and I have been after embargoed, anonymous reporting of simple
typos for about 15 years now. If a reader used a highlight or a permalink to
place them closer to the problem on GH that'd be even better.

Encouraging folks to interpret anybody's "View Source" as model PreTeXt would be
a big mistake. "If it looks good, it must be right," is a continual problem.

The source for this next exercise is very wrong, since it uses a list and not
tasks (not Tom's fault!). Looks good, though.

http://abstract.pugetsound.edu/aata/integers-exercises.html#aPA

And somebody did some one-off XSL to make the colored text happen here:

https://soundwriting.pugetsound.edu/pugetsound/book-one-author.html

I could find more. So maybe such a feature should be billed only as "Report a
Typo".

Instead, I would much prefer to see some effort directed to the "Showcase
Article", whose main purpose is to make an author go, "how do I do that in
mine?" We can easily make it "annotated" with "View Source" knowls.

https://pretextbook.org/examples/showcase/html/frontmatter.html

Rob

> Screenshot 2023-02-27 153515.png
>
> --
> 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/bfa61b4c-29f3-44bf-a5cc-a160965cd869n%40googlegroups.com <https://groups.google.com/d/msgid/pretext-dev/bfa61b4c-29f3-44bf-a5cc-a160965cd869n%40googlegroups.com?utm_medium=email&utm_source=footer>.

[kcri...@gmail.com]

I know I definitely use the "annotated" version of the Sample Article for this kind of purpose, so I think that for projects which are on GH (or Gitlab, or ...) this would be a very useful feature!

[kcri...@gmail.com]

I know I definitely use the "annotated" version of the Sample Article for this kind of purpose, so I think that for projects which are on GH (or Gitlab, or ...) this would be a very useful feature!

Sorry, having seen Rob's email I want to make it clear that I would find it useful to report things, though I admit I *also* use it in the Sample Article for seeing how to implement.  But I was primarily thinking of suggested improvements.

[Steven Clontz]

I would see this as an opt-in feature for more mature products that have a wide audience of potential contributors. Of course, the annotated sample article's current "View Source" knowls are buggy (displaying < rather than &lt; in TikZ, for instance), so this would also fix those errors for free.

[Rob Beezer]

On 2/28/23 08:54, Steven Clontz wrote:
> current "View Source" knowls are buggy (displaying < rather than &lt; in TikZ,
> for instance)

Is there an issue for that bug? Probably belongs on the PreTeXt side and not
the SL3X side.

Are there other bugs which would merit the description of "buggy"?

Rob

[Steven Clontz]

That's the only bug I know of offhand, since I ran into it during a demo yesterday. I don't know how the annotated article is generated so it's hard to contribute to it or understand its issues. I opened the issue here: https://github.com/PreTeXtBook/pretext/issues/1936

[Rob Beezer]

On 2/28/23 09:49, Steven Clontz wrote:
> I opened the issue here: https://github.com/PreTeXtBook/pretext/issues/1936

Thank-you. I've added some comments on how this feature might be improved.

Which is how I think open-source development should function. Rather than
making negative comments about the code written by other volunteers. That
creates a disincentive to continue contributing, and *nobody* is obliged to
stick around.

Rob

[Rob Beezer]

Well, that was wild. Definitely the innermost ring of escape-character hell.

1. You want a bare "<" to be seen by a reader of the sample article (not in
math, just text).

2. So author "&lt;" since "<" is for starting tags.

3. Now parse the source to make HTML output. XSL "sees" a "<" and escapes it
in HTML output as "&lt;".

4. But if you show that as the source, a browser will show it as "<", not what
was authored.

5. So break the escape sequence by converting the "&" to its escaped version,
"&amp;", thus needing "&amp;lt;" in the source for the "View Source" knowl.

6. It gets weirder. The sample article has passages that read, "To produce a <
type &lt;." Think about what that last bit was in the source and what it must
become in the View Soure knowl to render like the original source.

Anyway, turned out to be easier than it sounds. But don't break the first
character of "<chapter/>" in the process. ;-)

Homework:

Exercise 8.1
https://pretextbook.org/examples/sample-article/annotated/text-in-paragraphs.html#exercise-13

Rob

[Steven Clontz]

Thanks for that Rob.

I still believe there's value in a "View Source on GitHub/GitLab" button, particularly to emphasize that we embrace open-*source* content across the ecosystem, not just our software. And to encourage PRs instead of Issues when people find typos in the documents I'm responsible for. *blush*

I'm willing to take lead on implementation; I just need guidance on what approach would be acceptable.

[Oscar Levin]

It seems like such a button really belongs on the landing page for the book, which eventually we will also have the CLI generate.  And in the frontmatter.  

But perhaps this is another good use for the footer.  It seems most modern websites have footers that give credit to the software that generated it (like we do), as well as contact information for the thing the site represents (blogs have links to the writer's other projects, their social media, etc).  So a section in the footer that contains links to the book's landing page, perhaps to the author's page, maybe to the source of the book, all seem unobtrusive and reasonable.  

--

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/012cd109-1997-4a1c-af65-676b88fda42cn%40googlegroups.com.

[Steven Clontz]

For clarity, I'm proposing a button that goes directly to e.g. https://github.com/TeamBasedInquiryLearning/calculus/blob/main/source/02-DF/03.ptx so when someone finds a typo, they can search the immediate page they land on to find and correct it in a PR through GitHub's web interface.

Steven Clontz

https://clontz.org - steven...@gmail.com

To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-dev/CAOU9BaVW0mNuK7LUttmKipHiOy9-pDXVR4pSH68sRAfhZY3Gbw%40mail.gmail.com.

[Jason Siefken]

I'm not sure what other people do with highlighted text, but I think it would be cool if, when you highlighted a piece of text, a menu popped up and one of the items was "View PreTeXt" source, and another was "Report an Error".

If the manifest.xml file also contained pretext source links with every TOC item, this could be done fairly easily (provided the base URL was supplied somewhere).

To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-dev/CAOWT6TjPqRyXuMDR9YEpEjf1qeC814aeVcrMc8ejdAu1N3oNfQ%40mail.gmail.com.