[rkward-devel] writing docs [was: power analysis plugin]

[meik michalke]

hi,

i'll concentrate on this part:

Am Mittwoch, 8. Oktober 2014, 14:01:25 schrieb Thomas Friedrichsmeier:
> >  rk.set.comp("Example component")
> >  rk.XML.cbox(
> >    label="Cherry",
> >    value="cherry",
> >    help="Check this to get a cherry on top.")
> > 
> > without rk.set.comp() you'd have to 'add component="Example component"' to
> > the rk.XML.cbox() call, which is a bit annoying after the third time... to
> > see the stored text, run
> > 
> >  rk.get.rkh.prompter()
> 
> Not pretending, I understood this, completely, but sounds good. Will try
> when I have a bit of time (not today).

i've added your parts to the script now, hopefully when you look at the 
changes you get an idea how this works. but it's true, i should explain a bit 
more:

there has long been a function called rk.rkh.scan() in rkwarddev, which tries 
to generate a complete skeleton for an .rkh file from a given XML file (or XML 
object). it knows a list of XML tags which might need a <setting> node in the 
help file, and therefore automatically generates a file which is already 
structured according to the particular plugin component. but it still missed 
the actual text for each setting. this has changed yesterday.

with the recent SVN version of rkwarddev, all functions which generate those 
relevant XML nodes in the first place now have two additional arguments, 
"help" and "component" (as you can define several components in one script, 
naming the belonging component here was necessary). the interesting one is 
"help", which takes the information you would usually give as "text" to 
rk.rkh.setting(); that is, you souldn't need to call rk.rkh.setting() at all 
any more, and still get your help text to the right place in the .rkh file.

an example -- until recently:

  pwr.parameter.rad <- rk.XML.radio(label="Parameter to determine",
    options=list(
      "Power of test"=c(val="Power", chk=TRUE),
      "Sample size"=c(val="Sample size"),
      "Effect size"=c(val="Effect size"),
      "Significance level"=c(val="Significance level")
    ), id.name="rad_pwr_param")

  rk.rkh.scan(pwr.parameter.rad)

calling rk.rkh.scan() would have recognized <radio> as something to be 
documented and return a <setting> node for you to fill with text:

  <setting id="rad_pwr_param">
  </setting>

alternatively, you would manually call rk.rkh.setting() to create that node 
including text.

now, you can document the <radio> node at the same time you create it with 
rk.XML.radio():

  pwr.parameter.rad <- rk.XML.radio(label="Parameter to determine",
    options=list(
      "Power of test"=c(val="Power", chk=TRUE),
      "Sample size"=c(val="Sample size"),
      "Effect size"=c(val="Effect size"),
      "Significance level"=c(val="Significance level")
    ), id.name="rad_pwr_param",
    help="Parameter to estimate, given the others.",
    component="Power analysis")

  rk.rkh.scan(pwr.parameter.rad, component="Power analysis")

this call to rk.rkh.scan() will now return the complete <setting> node:

  <setting id="rad_pwr_param">
    Parameter to estimate, given the others.
  </setting>

and since rk.rkh.scan() can be invoked by rk.plugin.skeleton() and 
rk.plugin.component(), your help file is almost already written when you 
designed the XML elements. you still need to write a summary and usage 
section, but all *settings* can be documented "in place".

when i tested this, i soon noticed that copying the same "component" stuff to 
every function call will bloat the script. so there's also a function to set a 
current default component:

  rk.set.comp("Power analysis")

all relevant rk.XML.* functions have "component=rk.get.comp()" as the default 
value, which means 

  pwr.parameter.rad <- rk.XML.radio(label="Parameter to determine",
    options=list(
      "Power of test"=c(val="Power", chk=TRUE),
      "Sample size"=c(val="Sample size"),
      "Effect size"=c(val="Effect size"),
      "Significance level"=c(val="Significance level")
    ), id.name="rad_pwr_param",
    help="Parameter to estimate, given the others.")

will also get the job done if rk.set.comp() was called accordingly. one 
important thing: the component name must match the "name" argument given to 
rk.plugin.component(), or the "name" argument passed to "pluginmap" (the main 
component) in rk.plugin.skeleton(). otherwise it won't be found.

finally: setting "help" to FALSE will omit the XML node from the documentation 
-- something which wasn't possible with the previous scan method either.


viele grüße :: m.eik

-- 
  dipl. psych. meik michalke
  institut f"ur experimentelle psychologie
  abt. f"ur diagnostik und differentielle psychologie
  heinrich-heine-universit"at d-40204 d"usseldorf
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 828 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/rkward-devel/attachments/20141008/96b37fa1/attachment.sig>