flatdoc               package:mvbutils               R Documentation

_F_l_a_t-_f_o_r_m_a_t _d_o_c_u_m_e_n_t_a_t_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     'flatdoc' lets you edit plain-text documentation in the same file
     as your function definition. The documentation can be completely
     informal, or can be close to the standard on-screen appearance of
     R help files (and if so can be converted to actual Rd files by
     'doc2Rd'). This can be useful for your own notes, for informal
     distribution, and for formal distribution when you are trying to
     avoid managing dozens of separate source and documentation files.

_U_s_a_g_e:

     structure( function( ...) {body}, doc=flatdoc( EOF="<<end of doc>>"))

_A_r_g_u_m_e_n_t_s:

     EOF: character string showing when plain text ends, as in
          'readlines.mvb'

    body: replace with your function code

     ...: replace with your function arg list

_D_e_t_a_i_l_s:

     A combined function-and-documentation text file should contain
     your function code wrapped in a 'structure(' construct, followed
     by a line like this:

     , doc=flatdoc())

     The rest of the file is plain-text documentation, which will be
     formatted and shown by 'dochelp' when 'help' or '?' is called. The
     documentation can be very informal, but if you follow some
     guidelines you will be able to convert it automatically to an
     Rd-format file by calling 'doc2Rd'.

     When such a file is read in using 'source.mvb', the 'flatdoc' call
     will cause the rest of the file to be read in as plain text, and
     assigned to the 'doc' attribute of the function. Documentation can
     be terminated with this line:

     <<end of doc>>

     The above line will causes 'source.mvb' to revert to normal
     statement processing mode for the rest of the file. Note that
     vanilla 'source' will not respect 'flatdoc'; you do need to use
     'source.mvb'.

     Files in this format can be produced by
     'write.sourceable.function', or by hand. The 'fixr' editing system
     automatically outputs and inputs 'flatdoc' format for functions
     with flat-format documentation.

     On some text editors, you can modify syntax highlighting so that
     the "start of comment block" marker is set to the string
     "doc=flatdoc(".

     It's possible to use 'flatdoc' to read in more than one
     free-format text attribute. The 'EOF' argument can be used to
     distinguish one block of free text from the next.

     'flatdoc' should never be called from the command line; it should
     only appear in text files designed for 'source.mvb'.

     The 'fixr' editor interface automatically uses the 'flatdoc'
     approach to allow editing of source code and plain-text
     documentation in the same file. If you use a different editor
     interface, but like the idea of using 'flatdoc'-style
     documentation, then you will need to:

        *  make sure 'source.mvb' rather than 'source' is used to read
           in text files;

        *  if your system produces text files for the editor directly
           from function objects (which 'fixr' does), then make sure
           that the files are produced by 'write.sourceable.function'
           rather than 'print' or 'write' or 'cat'.

_V_a_l_u_e:

     Character vector of class 'docattr', as read from the
     'current.source()' (qv) connection.

_N_o_t_e:

     You can also write combined code-and-documentation functions whose
     documentation merely _refers_ to another function, like an alias
     in an Rd file. To refer to documentation stored with a function
     'x', instead of setting 'doc' to 'flatdoc()' at the end of your
     structure(...) construct, set 'doc' to 'list("x")'. The
     referencing can be several layers deep; the documentation of 'x'
     can refer to 'y', whose documentation refers to 'z', whose
     documentation is actually flatdoc()-style.

     If you are writing documentation for a group of functions
     together, you only need to 'flatdoc' one of them, say 'myfun1'.
     Informal help will work if you modify the others to e.g.

     myfun2 <- structure( function(...) { whatever},
     doc=list("myfun1"))

     If you are writing with 'doc2Rd' in mind and a number of such
     functions are to be grouped together, e.g. a group of "internal"
     functions in preparation for formal package release, you may find
     'make.usage.section' and 'make.arguments.section' helpful.

     One reason for needing 'flatdoc', rather than just putting
     ',doc="giant character string"', is that R requires a backslash at
     the end of each line of a multi-line string. This format is very
     painful to edit.

_A_u_t_h_o_r(_s):

     Mark Bravington

_S_e_e _A_l_s_o:

     'source.mvb', 'doc2Rd', 'dochelp', 'write.sourceable.function',
     'make.usage.section', 'make.arguments.section', 'fixr', the demo
     in "flatdoc.demo.R"

_E_x_a_m_p_l_e_s:

     ## Not run: 
     ## Put everything before the next comment into a text file <<your filename>>
     structure( function( x) {
      x*x
     }
     ,doc=flatdoc("<<end of doc>>"))
     Here is some informal documentation for the "SQUARE" function
     <<end of doc>>
     ## Now try SQUARE <- source.mvb( <<your filename>>); ?SQUARE
     ## Put everything before the next comment into a text file
     myfun <- structure( function(...) {}
     , att1=flatdoc( EOF="<<end of part 1>>")
     , att2=flatdoc( EOF="<<end of part 2>>"))
     This goes into "att1"
     <<end of part 1>>
     and this goes into "att2"
     <<end of part 2>>
     ## Now "source.mvb" that file, to create "myfun"
     cat( attr( myfun, "att1")) # This goes into "att1"
     cat( attr( myfun, "att2")) # This goes into "att2"
     ## End(Not run)

