We spoke about this before, but, as Bill pointed out recently, having blocks of code that cannot be evaluated (and that appears to be ending in commas) is going to be a source of confusion for users. Unless we place those pieces of code in the context of a large function call--by showing that large function call as one unit before the other pieces (and possibly referring to line numbers, which can be turned on)--we should probably just make use of variables in R.
We also have some irregular usage of semicolons in the documentation that needs addressed.
So the Optimization Script demo would be:
myExpMeanMatrix <- mxMatrix( type="Full", nrow=1, ncol=2, free=True, values=c(0,0), dimnames=list(NULL, selVars), name="expMean" )
myCholMatrix <- mxMatrix( type="Full", nrow=2, ncol=2, free=c(T,T,F,T), values=c(1,.2,0,1), dimnames=list(selVars, selVars), name="Chol" )
myExpCovAlg <- mxAlgebra( expression=Chol %*% t(Chol), name="expCov", dimnames=list(selVars, selVars) )
myData <- mxData( observed=testData, type="raw" )
myObj <- mxFIMLObjective( covariance="expCov", means="expMean" )
bivCorModel <- mxModel("bivCor", myExpMeanMatrix, myCholMatrix, myExpCovAlg, myData, myObj)
I think the confusion about "ending in a comma" obtains because people are not expecting functions with so many parameters... so it will pass promptly.
More enduringly, visual parsing is much easier when white-space indents are used
This is how I do mine:
http://pastie.textmate.org/private/zqy1iqxh9kwh5npztcsqq
It is then clear what is inside a function, and when the function call is over.
More use of explicit semi-colons also helps, as would a syntax coloring system: You could steal the one used in the pastie above.
PS: T ≠ True ≠ TRUE
You're right. One thing we need to write is a better syntax highlighter for R for both the site and documentation. I'll add it a ticket for it.
Personally, I don't think we should use semicolons as they aren't really Rish.
And, actually, in R, T = = TRUE.
re: "actually, in R, T = = TRUE"
> TRUE = FALSE
Error in TRUE = FALSE : invalid (do_set) left-hand side to assignment
> T = FALSE
> T==TRUE
[1] FALSE
>
I think it is a mistake to have unexecutable fragments in the yellow-backgrounded sections on pages like:
http://openmx.psyc.virginia.edu/docs/OpenMx/latest/Examples_Path.html#genetic-epidemiology-path-specification
It's not helpful or necessary.
Perhaps the standard should be that any yellow-section is copy and paste executable, and if the author wishes to draw attention to a small section which is not, then they should say "Thus the model can be names (see ‘share', line x below) instead of showing that fragment out of context.
Probably if exposition suggests breaking the function at a point which is not modular, then we might wish to re-factor or add a helper.
"Perhaps the standard should be that any yellow-section is copy and paste executable...."
Agreed.
Agreed, but sometimes it will be necessary to have already copy and paste executed prior slabs of code. Otherwise I think we'll need a different color in order to indicate that this slab is not copy-and-paste executable, because explaining a long script will naturally flip-flop between code fragments and descriptive text.
Important to keep the occasions just to the necessary some-times's, not the more ubiquitous most times.
It would be useful if the docs showed the script is in one column, and when the user does a roll-over on a yellow-backgrounded piece, the full script scrolls to show the hight-lighted area. Not too hard to implement given line number support.
If the full script is formated using <p> as a line marker or similar, then the how-to page a javascript function to read in the desired paragraphs (lines) from the script on the fly, and create the rollover scroll, something like this (inchoate pseudo code)
<script type="text/javascript" charset="utf-8">
function makeYelloHelp (startLine, endLine, scriptFileURL) {
helpText = "<p class=\"yellowHelp\">";
var scriptLines =document.getElementsByTagName("p");
</script>
that way the help writer just says a very english-like "as you can see in lines 10 through 12", except they write
As you can in <script makeYelloHelp(10,12,"mainscript" />
That also keeps things correct if the background script is edited.
We're using Sphinx which allows us to compile pdfs automatically. The interactive solution doesn't seem to me to work so well in printed form. I would argue that how we solve this problem should work for both the printed and html doc and that it should be able to continue to be automatically compiled.
I think if we are careful about how we set up code blocks (perhaps as a fully executable codeblock first and then chunked and explained pieces afterwords) we can obtain the learning we desire without needing to resort to diverging interactive and printed versions.
Adding the full script at the top, bottom, or along-side in a second column would certainly make thing much easier to follow, and maintain automation.
While I am a big fan of JavaScript and like your idea as an interface feature, I agree with Steve that this has to also work in printed form and add that it also has to work for those few users who have javascript-disabled/limited browsers. Providing the full block of code first and then referencing it via smaller blocks seems like it solves this problem. As a feature for all users, we can not only add line numbers to the full block, but have the smaller blocks display the numbers of the lines they were on in the larger block.
For instance, if the whole piece of code is 50 lines long, we might talk about one function call, displayed as follows:
...
The first argument of the code above creates an object of type mxMatrix as seen below....
...
The above code would be indented properly, however.
Line numbers help. I like that idea as long as we can make the line numbers be outside of the code block somehow so that the code block can still be cut and pasted without picking up the line numbers.