Logged-In As
ACCOUNT
Not Logged In
Add missing documentation for any one command (#2) BRL-CAD
Status: Closed Time to complete: 48 hrs Mentors: Sean Tags: documentation, docbook, xml, text editing

BRL-CAD is an extensive system with more than 400 commands and more than a million pages of documentation, but there are approximately 120 commands that are entirely undocumented:

a-d archer asc2g asc2pix bot-bldxf bottest brep_cube brep_simple brickwall btclsh burst bw-a bw-d bwish c-d chan_add clutter contours d-a damdf dauto dauto2 d-bw dconv ddisp d-f dfft d-i dmod double-asc dpeak dsel dsp_add dstat d-u dwin euclid_format euclid_unformat fbgammamod f-d fence fhor f-i g-adrt g-euclid1 g-jack globe g-off i-a i-d i-f ihist imod istat jack-g kurt lowp molecule nmgmodel nmg-sgp off-g pipe pipetest pix2g pix3filter pixcount pixelswap pixembed pixfields pixfieldsep pixflip-fb pixpaste pix-spm pix-yuv plstat pyramid rawbot remapid rlesortmap rletovcr room rtcell rtexample rtfrac rtrad rtsil rtsrv script-tab sketch solshoot sphflake spltest spm-fb ssampview syn tea tea_nmg testfree texturescale torii ttcp tube txyz-pl u-a u-bw u-d u-f umod ustat vcrtorle vegitation wall wdb_example xbmtorle xyz-pl yuv-pix

NOTE!  Some may have been completed, so check our other finished GCI tasks or ask us.

This task involves writing basic documentation for JUST ONE of those commands in the Docbook XML format. The command documentation should provide a one-sentence summary description, a detailed paragraph description (200+ words), explanation of all available command-line options, and one or more examples on how to use the command.

Code:

  • doc/docbook/system/man1/en/CMakeFiles.txt
  • doc/docbook/system/man1/en/*.xml
How to get started:
  1. You'll need a source checkout, see http://brlcad.org/wiki/Compiling
  2. You can use any of the existing xml files in that directory as a template starting point (see doc/docbook/articles/en/TEMPLATE.xml for Docbook examples)
  3. Learn the tool, find its source, write up the documentation
  4. You'll need to run svn add doc/docbook/system/man1/en/yourfile.xml
  5. You'll need to compile your xml file (make doc) to ensure it has no errors
  6. Review the html file it creates from your xml file
  7. You'll then submit your work as a single patch file, see http://brlcad.org/wiki/Patches
 
Uploaded Work
File name/URL File size Date submitted
patch-v1 7.0 KB December 21 2012 08:28 UTC
https://sourceforge.net/tracker/index.php?... n/a December 21 2012 08:29 UTC
report.txt 526 bytes December 21 2012 08:41 UTC
patch-v2 16.2 KB December 21 2012 09:27 UTC
patch-v3 16.2 KB December 21 2012 13:08 UTC
patch-v4 16.2 KB December 21 2012 13:22 UTC
patch-v5 16.2 KB December 21 2012 16:47 UTC
Comments
Yatharth Agarwal on December 19 2012 17:08 UTC Task Claimed

I would like to work on this task.

Andrei Popescu on December 19 2012 17:11 UTC Task Assigned

This task has been assigned to Yatharth Agarwal. You have 48 hours to complete this task, good luck!

Yatharth Agarwal on December 19 2012 17:12 UTC asc2g available?

I would like to document the asc2g function for this task. If not that, then the a-d one. The task description mentioned to make sure the commands haven't been already taken, so I want to know: Can I work on those?

Sean on December 19 2012 17:18 UTC both are available

Both/either are available and you didn't need to change tasks.  They are identical.  This one just provides more step-by-step information in response to questions received from people working on the first one (yourself included).  The goal and resulting patchfile expected is identical.


 

Yatharth Agarwal on December 19 2012 17:23 UTC OK

I preferred switching. I'll work on a-d as it's simpler ;) BTW, couldn't you have updated the previous task also?

Sean on December 19 2012 17:28 UTC no

Gee, didn't think of that...


No, tasks cannot be updated once they're assigned.


 


The simpler tools get scrutinized more carefully for completeness and perfection, so they're not usually any less work.  The only savings may be in learning what the simpler commands do is easier.  Good luck!

Yatharth Agarwal on December 19 2012 17:32 UTC :/

By "tasks cannot be updated once they're assigned", do you mean they can when they're not assigned?


 


Also, should I do a troff macro and use DocLifter or something to convert it or directly modify the template? I prefer the macro way. You can see instant results with it, too.

Sean on December 19 2012 17:44 UTC i do not

I did not mean that.  Once a task has been assigned to anyone, regardless of it's current assignment/completion state, it can no longer be edited.


The answer to your other question hasn't changed from what Daniel told you earlier.  The end result must be a valid Docbook 5 xml file integrated into our cmake build that generates good output in manpage and html format.  Our build system takes care of all that for you, so you just have to come up with the xml file.  Frankly don't care how you come up with the file so long as it's valid and gives proper output.


We've probably been using manpages and troff since before you've been born, so I can certainly understand your appreciation for it's simplicity!  The merits of Docbook, however, are FAR greater in the grand scheme of cross-platform development, which is why we migrated our 500+ existing manpages to that format.  It's opened up a lot of possibilities that were not at all possible before. 

Yatharth Agarwal on December 21 2012 08:19 UTC What do I submit?

I've created the diff/patch file. The wiki says to upload it to SourceForge, but the task description says to just upload it over here. Should I just upload to SourceForge and submit the URL to the patch here?


Also, I completely agree with you on DocBook v/s Troff. DocBook is waay more powerful and controllable.


And as for the task description, why didnt you just link to a wiki page over which you have control so you can update task descriptions like some other projects?


Thanks.

Yatharth Agarwal on December 21 2012 08:28 UTC Ready for review

The work on this task is ready to be reviewed.

Daniel Rossberg on December 21 2012 08:29 UTC Upload it here

...

Yatharth Agarwal on December 21 2012 08:38 UTC Summary

Here are the things I did:-



  • added a asc2g.xml DocBook file in the brlcad/doc/docbook/system/man1/en/ folder

  • modified CMakeLists.txt (which in the task description was mistakingly mentioned as CMakeFiles.txt) to compile asc2g.xml when making and to comment line which outputted g2asc's man page for both commands


And the results after making were:-



  • .built/bin/brlman asc2g works

  • .built/share/doc/html/man1/en/asc2g.html also displays fine

  • .built/share/man/man1/asc2g.1 screws up for some reason

Daniel Rossberg on December 21 2012 08:46 UTC Ok, about the patch-v1


  • Simply remove the set_source_files_properties() line.  Keeping senseless code in a filemakes it hard to read.  The version control system (Subversion for BRL-CAD) will keep track of it.

  • It looks like you need to make changes to the g2asc.xml too as it contains the old man page.

Daniel Rossberg on December 21 2012 08:46 UTC Task Needs More Work

One of the mentors has sent this task back for more work. Talk to the mentor(s) assigned to this task to satisfy the requirements needed to complete this task, submit your work again and mark the task as complete once you re-submit your work.

Yatharth Agarwal on December 21 2012 08:52 UTC Modify g2asc.xml?

So I modify the g2asc man page to make it only for that command?

Daniel Rossberg on December 21 2012 08:55 UTC Yes

It was the man page for two commands (asc2g and g2asc).  Now asc2g gets its own man page.

Yatharth Agarwal on December 21 2012 09:28 UTC Ready for review

The work on this task is ready to be reviewed.

Yatharth Agarwal on December 21 2012 09:30 UTC Deadline Extension requested

If the task gets rejected now, can I have a deadline extension of 1 day or so, please?

Daniel Rossberg on December 21 2012 09:54 UTC Deadline extended

The deadline of the task has been extended with 1 days and 0 hours.

Yatharth Agarwal on December 21 2012 10:30 UTC Can you review it?

patch-v2 includes the new, updated g2asc.xml file. Can you please review it?


Also, the deadline extension wasn't necessary. I managed to convince my mom to let me take my laptop :)

Daniel Rossberg on December 21 2012 12:26 UTC The USAGE section

refers to g2asc (in asc2g man-page).

Daniel Rossberg on December 21 2012 12:26 UTC Task Needs More Work

One of the mentors has sent this task back for more work. Talk to the mentor(s) assigned to this task to satisfy the requirements needed to complete this task, submit your work again and mark the task as complete once you re-submit your work.

Yatharth Agarwal on December 21 2012 13:09 UTC Ready for review

The work on this task is ready to be reviewed.

Daniel Rossberg on December 21 2012 13:20 UTC You forgot to change the xml:id too

<refsect1 xml:id= ...

Daniel Rossberg on December 21 2012 13:20 UTC Task Needs More Work

One of the mentors has sent this task back for more work. Talk to the mentor(s) assigned to this task to satisfy the requirements needed to complete this task, submit your work again and mark the task as complete once you re-submit your work.

Yatharth Agarwal on December 21 2012 13:23 UTC Ready for review

The work on this task is ready to be reviewed.

Daniel Rossberg on December 21 2012 14:07 UTC Example vs. Examples

You called the section exaples (plural).  But comparin it with the other man-pages and the g2asc as it was before I'm fairly sure that it should be example (singular).

Daniel Rossberg on December 21 2012 14:07 UTC Task Needs More Work

One of the mentors has sent this task back for more work. Talk to the mentor(s) assigned to this task to satisfy the requirements needed to complete this task, submit your work again and mark the task as complete once you re-submit your work.

Yatharth Agarwal on December 21 2012 16:46 UTC Ready for review

The work on this task is ready to be reviewed.

Erik on December 22 2012 14:12 UTC Applied with r54114

.

Erik on December 22 2012 14:12 UTC Task Closed

Congratulations, this task has been completed successfully.