{"id":310,"date":"2012-12-20T09:24:04","date_gmt":"2012-12-20T09:24:04","guid":{"rendered":"http:\/\/ahay.org\/blog\/?p=310"},"modified":"2015-08-04T23:51:33","modified_gmt":"2015-08-04T23:51:33","slug":"the-role-of-selfdocs-in-madagascar","status":"publish","type":"post","link":"https:\/\/ahay.org\/blog\/2012\/12\/20\/the-role-of-selfdocs-in-madagascar\/","title":{"rendered":"The role of selfdocs in Madagascar"},"content":{"rendered":"

Documentation is an important component of any software product. Madagascar has reproducible documents, wiki pages, example scripts, and source code. Carefully selected variable names and comments in the source code can provide critical assistance to the next developer that extends a program. Every Madagascar program also has selfdoc that appears with the program is executed without parameters. The selfdoc is simple ASCII text that prints to the terminal to help the end users input to the program. There are tools to reformat the selfdoc into other formates like HTML, LaTeX, and man pages (see the selfdoc on sfdoc). Be kind to your end users with a good selfdoc, in a few months YOU might find it useful!
\nUser documentation simply describes how a program is used. A general overview of the program, a description of all the features, and each parameter needs to be described. A description of the input and output data is important, especially with the program is intended to be used in combination with other programs (for example a program might expect input or output data to be forward or inverse Fourier transformed, or the program might expect the input or output data to be transposed). Users often find example flows very helpful. Include the flows in the selfdoc or recommend other useful documents. In depth theory is better left to reproducible documents or printed papers.
\nStandard sections in the selfdoc are:
\nNAME
\nThe name of the command or function. This comes from the name file containing your source code.
\nDESCRIPTION
\nA one-line description of what it does. This comes from the first line of the comment at the very beginning of your source code.
\nSYNOPSIS
\nA terse list of the program’s parameters and illustration of possible values. Experienced users can use this as a reminder of parameter names, whether integer or floating point numbers can be input, and the defaults. This is automatically created for the source by looking for functions that get parameters from the command line (eg sf_getint, sf_getfloat, sf_getstring).
\nCOMMENTS
\nThis is a free form area that contains everything after the first line in the comment at the very beginning of the program’s source code. This is where you describe the input and output data, how you intend the program to be used with other programs, and provide examples. EXAMPLES are often easy to produce and are likely to be exactly what the end user needs. You should also recommend key parameter settings. Some parameter values might be difficult to select, but the research geophysicist and software developer are probably better qualified than a new end user to make initial settings of the parameters. You may be able to recommend tests that can help select improved settings. Be kind to your users, you are fortunate to have someone use and extend your technology.
\nPARAMETERS
\nA list of each parameter, the type (integer, float, string, or a list of integers, floats or strings) and the default. This is automatically created from the source code from the name of the function (sf_getint, sf_getfloat, sf_getstring, …). Each parameter is also described using the comment in the source code immediately following the sf_get function call.
\nUSED IN
\nThis sections is automatically created when the program is created. The Madagascar build system searches the main Madagascar directory to find all the places the program is used. A user can use these examples as a template for her processing needs.
\nSOURCE
\nThis sections is automatically created when the program is created. The Madagascar build system discovers the location of the source code and adds it to the selfdoc.
\nExample selfdoc for the program sffold<\/a> is:
\nNAME
\nsffold
\nDESCRIPTION
\nMake a seismic foldplot\/stacking chart.
\nSYNOPSIS
\nsffold < in.rsf > out.rsf verbose=1 o1= o2= o3= n1= n2= n3= d1= d2= d3= label1= label2= label3=
\nCOMMENTS
\nThis is a general 3D histogram program implemented to create foldplot or
\nstacking charts on a 3d project from trace headers. Axis1, 2 and 3 define
\nthe bins for the output fold map. These are usually (offset,xline,iline),
\nbut you might want to compute some other histogram. This can be done by
\nselecting other segy headers using label1, 2 and 3.
\nSee also fold= option in sfbin for creating 2D histograms.
\nEXAMPLES:
\nTo make a stacking chart movie showing fold(xline,offset) for each inline
\nfrom a 3d segyfile:
\nsfsegyread tfile=tteapot.rsf hfile=teapot.asc bfile=teapot.bin \\
\ntape=npr3_field.sgy > teapot.rsf
\n# read the tfile, which contains the segy trace headers
\n< tteapot.rsf sfdd type=float \\\n| sffold verbose=1 \\\no1=0 n1=96 d1=200 label1=offset \\\no2=1 n2=188 d2=1 label2=xline \\\no3=1 n3=345 d3=1 label3=iline \\\n>foldplot.rsf
\n\n","protected":false},"excerpt":{"rendered":"

Documentation is an important component of any software product. Madagascar has reproducible documents, wiki pages, example scripts, and source code. Carefully selected variable names and comments in the source code can provide critical assistance to the next developer that extends a program. Every Madagascar program also has selfdoc that appears with the program is executed […]<\/p>\n","protected":false},"author":12,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_import_markdown_pro_load_document_selector":0,"_import_markdown_pro_submit_text_textarea":"","activitypub_content_warning":"","activitypub_content_visibility":"local","activitypub_max_image_attachments":4,"activitypub_interaction_policy_quote":"","footnotes":""},"categories":[5],"tags":[],"class_list":["post-310","post","type-post","status-publish","format-standard","hentry","category-documentation"],"_links":{"self":[{"href":"https:\/\/ahay.org\/blog\/wp-json\/wp\/v2\/posts\/310","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/ahay.org\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/ahay.org\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/ahay.org\/blog\/wp-json\/wp\/v2\/users\/12"}],"replies":[{"embeddable":true,"href":"https:\/\/ahay.org\/blog\/wp-json\/wp\/v2\/comments?post=310"}],"version-history":[{"count":1,"href":"https:\/\/ahay.org\/blog\/wp-json\/wp\/v2\/posts\/310\/revisions"}],"predecessor-version":[{"id":605,"href":"https:\/\/ahay.org\/blog\/wp-json\/wp\/v2\/posts\/310\/revisions\/605"}],"wp:attachment":[{"href":"https:\/\/ahay.org\/blog\/wp-json\/wp\/v2\/media?parent=310"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/ahay.org\/blog\/wp-json\/wp\/v2\/categories?post=310"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/ahay.org\/blog\/wp-json\/wp\/v2\/tags?post=310"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}