Documentation of <program> / General Doc questions

[J David Eisenberg]

Suggestions for this page: https://pretextbook.org/doc/guide/html/topic-program-console.html

1) Note that the <program> element must have a child <input> element; otherwise the program listing doesn’t show up.

2) Perhaps include an example of both.

In general:

3) I see that attributes are preceded with an @ (for example, @language on the program/console page). Is it a good idea to include the at sign? It may be confusing to people who are not familiar with XML.

4) Where is the github source for the guide (starting at https://pretextbook.org/doc/guide) so that people can make pull requests?

[Rob Beezer]

Dear David,

Thanks very much for the suggestions. See below.

On 11/6/22 07:41, J David Eisenberg wrote:
> Suggestions for this page:
> https://pretextbook.org/doc/guide/html/topic-program-console.html
>
> 1) Note that the <program> element must have a child <input> element; otherwise
> the program listing doesn’t show up.

Yes, that trips *me* up all the time. But it is good that we have structured
"program" since it now could benefit from a "title" when employed as an activity
on Runestone.

> 2) Perhaps include an example of both.

I've tried not to put too many examples in the Guide, though we do have the
"Basics" part that might be a good home, with a cross-reference from elsewhere.

> In general:
>
> 3) I see that attributes are preceded with an @ (for example, @language on the
> program/console page). Is it a good idea to include the at sign? It may be
> confusing to people who are not familiar with XML.

Yes, I use that a lot. I forget where I picked it up. And I've seen it trip up
people by putting the "@" in their source, including me. In the narrative, I
try to always use the word 'attribute' after this construction, as in "use the
@language attribute". Then it makes sense in isolation (I hope) in summary
lists, etc. Pretty well embedded, and you may be the first to question it.

Some explanation here, which is a little late:

Section 26.1: Publication File
https://pretextbook.org/doc/guide/html/publication-file.html#publication-file

Maybe something similar needs to go very early (or this could move and be
replaced by a cross-reference). Essential for reading the compact publication
file reference:

Chapter 43: Publication File Reference
https://pretextbook.org/doc/guide/html/publication-file-reference.html#publication-file-reference

> 4) Where is the github source for the guide (starting at
> https://pretextbook.org/doc/guide) so that people can make pull requests?

Main page:
https://pretextbook.org/

Link in "Code" section:
https://github.com/PreTeXtBook/pretext

Organization with highly-related repos:
https://github.com/PreTeXtBook

A pull request with improvements would be very welcome! See the following for a
rough survey of how we operate. Requesting a membership on "pretext-dev" would
be a good thing to do next.

Appendix A: Welcome to the PreTeXt Community
https://pretextbook.org/doc/guide/html/welcome.html#welcome

Rob


>
> --
> You received this message because you are subscribed to the Google Groups
> "PreTeXt support" group.
> To unsubscribe from this group and stop receiving emails from it, send an email
> to pretext-suppo...@googlegroups.com
> <mailto:pretext-suppo...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/pretext-support/10c3c20e-0150-4c13-b7a7-7c894beb3a1bn%40googlegroups.com <https://groups.google.com/d/msgid/pretext-support/10c3c20e-0150-4c13-b7a7-7c894beb3a1bn%40googlegroups.com?utm_medium=email&utm_source=footer>.