At Play With J/EditingGuidelines

The following are editing guidelines for the At Play With J articles.

Editing

The essential requirement is that the code work in the current version of J. Stylistic improvements can also be made where they do not detract from the text. MoinMoin formatting should be kept to a minimum, so as to simplify creation of the final document.

Testing should entail copy/pasting each line into J to check it runs, because that's how readers are most likely to use the book. Ideally code should have been copy/pasted from a J session.

Use ascii box drawing characters. If necessary, in the J session, select Tools|Toggle Ascii Box Drawing.

Use global assignment where code is likely to be included in a script, and not just typed into the session.

Typical changes will include:

• replace x. y. by x y

• replace obsolete trains with explicit definitions

• use N V V forks where possible (instead of N"_ V V)

• use correct library pathnames for loading scripts. Where a verb is required from a script that exists both as part of an Addon and as a system script, use the Addon.

• update text where no longer correct or relevant

• append notes where a relevant facility has been added to the system (e.g. q: for factorization)

Layout

• use structural wiki markup rather than text formatting. This makes it easier to read the source and generate output suitable for publication

• for J code where a noun is assigned and immediately afterwards displayed, prefer the convention:

    ]mynoun=: <create mynoun>
  <display of mynoun>

and not:

    mynoun=: <create mynoun>
    mynoun
  <display of mynoun>

See the Giddyap article for an example of layout.

Method

Editor's comments:

In general go for a "conservative" revision, ie just get it to work, not improve the J style (except where Gene is explicitly discussing J as a language rather than a tool, and J as-it-was would be misleading).

What I see good to preserve is the math investigative thinking which Gene is so good at. Too much math exposition covers its tracks a-la Gauss. Okay it makes the author look smarter but it's less helpful for a math scholar. To me this collection is not a masterclass in J coding but in using J in authentic math research, messy as that often is. Where Gene misses a stylistic trick, that can be picked up in a footnote or an end-note.

Some papers I envisage as generating quite a bit of discussion on the forum re how best to handle them. Eg the "cross that bridge" paper.