On 4/15/21 6:19 PM, Mendalski wrote:

You need to make the first line into a comment because it is not a
correct command on its own. The location of the highlight is not always
going to be helpful (though it will help if the command you have typed
is almost correct.

// a_small_cube.scad

cube(size=10)

That is wrong. It seems they have put in the file name, for some obscure
reason. Leave out the first line.

On 15/04/2021 23:19, Mendalski wrote:

Than you Ray, Michael, and Algot for your help. I will stick with the
PDF instructions you sent.

Dmend

On 4/15/21 5:19 PM, Mendalski wrote:

[ This is a discussion of how the tutorial might be improved to avoid
this confusion. ]

On 4/15/2021 3:19 PM, Mendalski wrote:

This is indeed confusing.  I went to go see if I could fix the tutorial,
but this pattern is used throughout so it's not a simple point fix.

Here's what it looks like:

Knowing the language and that there's an issue here, it's easy to see
that "a_small_cube.scad" is in italics, and the cube() invocation is in
a different font, in a box, but (a) files haven't been covered yet, (b)
the inner box is subtle, and (c) it's easy to miss the font change.

So what should it look like?

Maybe make the file name be more distinct?

Maybe move it into the title?

(But note the double box, which is kind of strange.  The inner box is
how Wikibooks is styling <pre>.)

Wikipedia programming language samples look like

or

but do not have a title ("Code") or file name ("a_small_cube.scad").

Or something else?

My suggestion:

• Do not include the file name in the example.  (If there's an example
  where the file name is important, as for example a discussion of
  "use <name.scad>", include it in a comment.)
• Include the file name in a Wikibooks comment (invisible to the
  reader); it looks like there's an intent to match up file names to
  the resulting images.
• Use the Wikipedia numbered style.
• Use lang="text".  Although others, like lang="C", will produce some
  syntax highlighting, I doubt any of them are exactly right for
  OpenSCAD.  Or maybe lang="C" until we find a case where it doesn't
  look good.

Any thoughts?

On 16.04.21 02:20, Jordan Brown wrote:

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.

ciao,
Torsten.

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

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.