discuss@lists.openscad.org

OpenSCAD general discussion

View all threads

Re: Tutorial example style (was Re: Newbie with Parser Error Line 1)

JB
Jordan Brown
Thu, Apr 22, 2021 3:28 AM

OK, I was what the Wikipedia people call WP:BOLD, and went ahead and set
up a template and changed over the first two examples at
https://en.wikibooks.org/w/index.php?title=OpenSCAD_Tutorial/Chapter_1

I didn't rig a link to github, because that's not set up.  Instead, I
made the caption be a link to the WikiBooks page that holds the
example.  I'm not sure on whether it really needs to be at github too,
since it must be at WikiBooks.  WikiBooks has an edit history, and
allows public-ish editing, so it's not clear that github adds anything.

The exact layout isn't my favorite - I'd prefer to do something more in
the style that Wikipedia uses for samples - but I haven't figured out
how to make that work and I didn't want to change too much about the
presentation.  The magic of using a template is that if it's decided to
use a different layout, you just change the template and all of the
examples change.

It looks like so:

Did anybody have any thought on this presentation or on the underlying
document/template structure?  Is there anybody who considers
themselves to be the lead editor on the tutorial?

On 4/17/2021 9:30 PM, Jordan Brown wrote:

On 4/17/2021 10:14 AM, Torsten Paul wrote:

On 16.04.21 02:20, Jordan Brown wrote:

Maybe move it into the title?

I like that option best, it might be useful to have a file
name that could be matched (or even linked?) against a github
repo with all the files.

Here's a structure that is in some ways convenient.

I created a template {{User:Jordan Brown/sandbox/tmpl}}.  Its
simplest invocation is

{{User:Jordan Brown/sandbox/OpenSCADExample|name=a_small_cube}}

which generates:

You can see this live at
https://en.wikibooks.org/wiki/User:Jordan_Brown/sandbox/demo .

What it does, in this simple invocation, with a name FOO, is:

So the idea is that you put this simple reference into the main
document, and you create a page FOO with the OpenSCAD program, and an
image file FOO.jpg, and the template takes care of putting them
together into the preferred form.

I also put together a slightly different template OpenSCADExample2,
that produces this, which I like a little better:

... but I'm not entirely happy with the title format.

The tricky part of this is in getting it to transclude a page
without processing any wikitext on that page, so that the FOO page
can contain precisely the OpenSCAD program, without needing any
protective markup.  The mechanism that I found, the "msgnw:"
modifier, seems to work but there are hints that there may be a few
kinds of wikitext that will still be processed.

Of course, this requires that the page containing the example, the
image, and the source file on github have the same name.  That could
be viewed as a limitation, or it could be viewed as a feature
encouraging structure.  The current implementation of the template
allows for specifying the name of the image separately, as img=BAR,
and allows specifying the content directly (instead of via another
page) as content=WHATEVER.  There could be a similar override for the
github link, but isn't yet.  The image type defaults to jpg, but can
be overridden with imgtype=XXX.

All of the details are easily changed, at least until we start using it.

Of course it would get put somewhere in the main template namespace,
not in my sandbox.

The key feature is that one template then controls the format of all
examples throughout the book.

OK, I was what the Wikipedia people call WP:BOLD, and went ahead and set up a template and changed over the first two examples at https://en.wikibooks.org/w/index.php?title=OpenSCAD_Tutorial/Chapter_1 I didn't rig a link to github, because that's not set up.  Instead, I made the caption be a link to the WikiBooks page that holds the example.  I'm not sure on whether it really needs to be at github too, since it must be at WikiBooks.  WikiBooks has an edit history, and allows public-ish editing, so it's not clear that github adds anything. The exact layout isn't my favorite - I'd prefer to do something more in the style that Wikipedia uses for samples - but I haven't figured out how to make that work and I didn't want to change too much about the presentation.  The magic of using a template is that if it's decided to use a different layout, you just change the template and all of the examples change. It looks like so: > Did anybody have any thought on this presentation or on the underlying > document/template structure?  Is there anybody who considers > themselves to be the lead editor on the tutorial? > > On 4/17/2021 9:30 PM, Jordan Brown wrote: >> On 4/17/2021 10:14 AM, Torsten Paul wrote: >>> On 16.04.21 02:20, Jordan Brown wrote: >>>> Maybe move it into the title? >>> I like that option best, it might be useful to have a file >>> name that could be matched (or even linked?) against a github >>> repo with all the files. >> >> Here's a structure that is in some ways convenient. >> >> I created a template {{User:Jordan Brown/sandbox/tmpl}}.  Its >> simplest invocation is >> >> {{User:Jordan Brown/sandbox/OpenSCADExample|name=a_small_cube}} >> >> which generates: >> >> >> You can see this live at >> https://en.wikibooks.org/wiki/User:Jordan_Brown/sandbox/demo . >> >> What it does, in this simple invocation, with a name FOO, is: >> >> * Generates a caption with a link to >> https://github.com/openscad/examples/blob/master/FOO.scad >> * Inside a gold box, protected from wikitext processing, >> transcludes >> https://en.wikibooks.org/wiki/User:Jordan_Brown/sandbox/FOO >> * Brings in the image [[File:FOO.jpg]] at a size of 680px. >> >> So the idea is that you put this simple reference into the main >> document, and you create a page FOO with the OpenSCAD program, and an >> image file FOO.jpg, and the template takes care of putting them >> together into the preferred form. >> >> I also put together a slightly different template OpenSCADExample2, >> that produces this, which I like a little better: >> >> ... but I'm not entirely happy with the title format. >> >> The tricky part of this is in getting it to transclude a page >> *without* processing any wikitext on that page, so that the FOO page >> can contain precisely the OpenSCAD program, without needing any >> protective markup.  The mechanism that I found, the "msgnw:" >> modifier, seems to work but there are hints that there may be a few >> kinds of wikitext that will still be processed. >> >> Of course, this requires that the page containing the example, the >> image, and the source file on github have the same name.  That could >> be viewed as a limitation, or it could be viewed as a feature >> encouraging structure.  The current implementation of the template >> allows for specifying the name of the image separately, as img=BAR, >> and allows specifying the content directly (instead of via another >> page) as content=WHATEVER.  There could be a similar override for the >> github link, but isn't yet.  The image type defaults to jpg, but can >> be overridden with imgtype=XXX. >> >> All of the details are easily changed, at least until we start using it. >> >> Of course it would get put somewhere in the main template namespace, >> not in my sandbox. >> >> The key feature is that one template then controls the format of all >> examples throughout the book. >> >> >
JB
Jordan Brown
Thu, Apr 22, 2021 3:40 AM

On 4/21/2021 8:28 PM, Jordan Brown wrote:

I didn't rig a link to github, because that's not set up.  Instead, I
made the caption be a link to the WikiBooks page that holds the
example.  I'm not sure on whether it really needs to be at github too,
since it must be at WikiBooks.  WikiBooks has an edit history, and
allows public-ish editing, so it's not clear that github adds anything.

A problem with that theory is that when the page that contains the
example is viewed, e.g. at
https://en.wikibooks.org/wiki/OpenSCAD_Tutorial/examples/a_small_cube
it is processed as wikitext.  Being processed as wikitext is not healthy
for OpenSCAD programs and other living things.

You can see it "correctly" by editing the source, but encouraging people
to edit the page source doesn't seem good.

On 4/21/2021 8:28 PM, Jordan Brown wrote: > I didn't rig a link to github, because that's not set up.  Instead, I > made the caption be a link to the WikiBooks page that holds the > example.  I'm not sure on whether it really needs to be at github too, > since it must be at WikiBooks.  WikiBooks has an edit history, and > allows public-ish editing, so it's not clear that github adds anything. A problem with that theory is that when the page that contains the example is viewed, e.g. at https://en.wikibooks.org/wiki/OpenSCAD_Tutorial/examples/a_small_cube it is processed as wikitext.  Being processed as wikitext is not healthy for OpenSCAD programs and other living things. You can see it "correctly" by editing the source, but encouraging people to edit the page source doesn't seem good.
M
MichaelAtOz
Thu, Apr 22, 2021 5:29 AM

I'm not sure moving the example code out of the page (ie the chapter/section) is a good idea.

It complicates editing, if you are just taking about the tutorial, maybe as it is rather static.

Also won't it be a PITA creating all those pages?


From: Jordan Brown [mailto:openscad@jordan.maileater.net]
Sent: Thu, 22 Apr 2021 13:41
To: OpenSCAD
Subject: [OpenSCAD] Re: Tutorial example style (was Re: Newbie with Parser Error Line 1)

On 4/21/2021 8:28 PM, Jordan Brown wrote:

I didn't rig a link to github, because that's not set up.  Instead, I made the caption be a link to the WikiBooks page that holds the example.  I'm not sure on whether it really needs to be at github too, since it must be at WikiBooks.  WikiBooks has an edit history, and allows public-ish editing, so it's not clear that github adds anything.

A problem with that theory is that when the page that contains the example is viewed, e.g. at
https://en.wikibooks.org/wiki/OpenSCAD_Tutorial/examples/a_small_cube
it is processed as wikitext.  Being processed as wikitext is not healthy for OpenSCAD programs and other living things.

You can see it "correctly" by editing the source, but encouraging people to edit the page source doesn't seem good.

--
This email has been checked for viruses by AVG.
https://www.avg.com

I'm not sure moving the example code out of the page (ie the chapter/section) is a good idea. It complicates editing, if you are just taking about the tutorial, maybe as it is rather static. Also won't it be a PITA creating all those pages? _____ From: Jordan Brown [mailto:openscad@jordan.maileater.net] Sent: Thu, 22 Apr 2021 13:41 To: OpenSCAD Subject: [OpenSCAD] Re: Tutorial example style (was Re: Newbie with Parser Error Line 1) On 4/21/2021 8:28 PM, Jordan Brown wrote: I didn't rig a link to github, because that's not set up. Instead, I made the caption be a link to the WikiBooks page that holds the example. I'm not sure on whether it really needs to be at github too, since it must be at WikiBooks. WikiBooks has an edit history, and allows public-ish editing, so it's not clear that github adds anything. A problem with that theory is that when the page that contains the example is viewed, e.g. at https://en.wikibooks.org/wiki/OpenSCAD_Tutorial/examples/a_small_cube it is processed as wikitext. Being processed as wikitext is not healthy for OpenSCAD programs and other living things. You can see it "correctly" by editing the source, but encouraging people to edit the page source doesn't seem good. -- This email has been checked for viruses by AVG. https://www.avg.com
TP
Torsten Paul
Thu, Apr 22, 2021 9:32 AM

On 22.04.21 07:29, MichaelAtOz wrote:

I'm not sure moving the example code out of the page (ie the
chapter/section) is a good idea.

Yes, I agree. Looking more at templates to get a consistent
formatting is great, and may even help efforts to ship the
documentation for offline use at some point.

But I think the content, including the example source code
should be fully included in normal pages. The github repo I
mentioned was more meant as additional resource for easier
bulk downloading of all examples and being able to load the
files instead of typing / copy&paste.

ciao,
Torsten.

On 22.04.21 07:29, MichaelAtOz wrote: > I'm not sure moving the example code out of the page (ie the > chapter/section) is a good idea. Yes, I agree. Looking more at templates to get a consistent formatting is great, and may even help efforts to ship the documentation for offline use at some point. But I think the content, including the example source code should be fully included in normal pages. The github repo I mentioned was more meant as additional resource for easier bulk downloading of all examples and being able to load the files instead of typing / copy&paste. ciao, Torsten.
JB
Jordan Brown
Thu, Apr 22, 2021 4:31 PM

I'm not wedded to the idea of putting the source in a separate page.

I kind of liked that idea because it appeared to (maybe) allow putting
the example in verbatim, and have the invocation have minimal
boilerplate.  Perhaps then the text could be mirrored from github, and
the images automatically created.

I'll look into other techniques.  I'm struggling a bit with how to wrap
a template invocation around verbatim text, and then how to feed that
verbatim text into processing in the template, while keeping the
boilerplate to a minimum and keeping all of the style control in the
template.

I'm not wedded to the idea of putting the source in a separate page. I kind of liked that idea because it appeared to (maybe) allow putting the example in verbatim, and have the invocation have minimal boilerplate.  Perhaps then the text could be mirrored from github, and the images automatically created. I'll look into other techniques.  I'm struggling a bit with how to wrap a template invocation around verbatim text, and then how to feed that verbatim text into processing in the template, while keeping the boilerplate to a minimum and keeping all of the style control in the template.