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
- You'll need a source checkout, see http://brlcad.org/wiki/Compiling
- 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)
- Learn the tool, find its source, write up the documentation
- You'll need to run svn add doc/docbook/system/man1/en/yourfile.xml
- You'll need to compile your xml file (make doc) to ensure it has no errors
- Review the html file it creates from your xml file
- You'll then submit your work as a single patch file, see http://brlcad.org/wiki/Patches
| File name/URL | File size | Date submitted | |
|---|---|---|---|
| patch-v1 | 12.0 KB | December 23 2012 15:48 UTC | |
| patch-v2 | 15.2 KB | December 23 2012 18:53 UTC | |
| asc2pix.1 | 3.5 KB | December 23 2012 19:04 UTC | |
| http://paste.ubuntu.com/1460175/ | n/a | December 23 2012 19:09 UTC | |
| patch-v3 | 14.2 KB | December 24 2012 06:03 UTC | |
| asc2pix.html | 5.3 KB | December 24 2012 06:03 UTC | |
| pix2asc.html | 5.3 KB | December 24 2012 06:04 UTC | |
| asc2pix.1 | 3.5 KB | December 24 2012 06:04 UTC | |
| tar-v3.tar.gz | 10.0 KB | December 24 2012 06:04 UTC | |
| tar-v4.tar.gz | 10.0 KB | December 25 2012 07:19 UTC | |
| patch-v5 | 12.7 KB | December 25 2012 17:57 UTC | |
| tar-v6.tar.gz | 10.0 KB | December 25 2012 17:57 UTC |
I would like to work on this task.
I hope you don't mind me taking this task...
This task has been assigned to Yatharth Agarwal. You have 48 hours to complete this task, good luck!
...
I want to do it on asc2pix. Is it available?
The work on this task is ready to be reviewed.
Nice work noticing that the documentation was already written so you mostly had to separate the two. I do notice, however, that you didn't include an example. There needs to be at least one example.
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.
The work on this task is ready to be reviewed.
I added an example situation where the commands might come in handy, and I used more semantic tags instead of emphasis tags everywhere.
Would you submit the html output?
Also, glancing at the text of the manual page, it does not appear to be accurate. It mentions using the -O option, please verify for accuracy.
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.
Actually, supplying the -O option to rt(1) makes it ouput a dpix (i.e., a double-precision color pixel file) rather than a pix(5) one. I couldn't find any info on whther this format was actually portable — in the man pages, HISTORY sections, the online documentation, or otherwise, — so I left it like that. The dpix-pix(1) command converts it back to pix.
Do you think I should remove that sentence altogether? Or just mention that supplying the -O option make it output the file in dpix format which might be portable?
And I'll submit the HTML file, no worries. Thanks.
The work on this task is ready to be reviewed.
I removed the offending statement and cut out use of empahasis tags almost altogether where semantic tags could achieve the same things. I submitted the 4 files and a archive containing all of them.
Note: while the HTML page displays fine in Chrome and Chromium, Firefox seems to have some trouble with the encoding. More specifically, the hyphen and some other characters appear as Æ and stuff.
Having an example is good, but having one that refers to third-party tools that the user may or may not have available is not good. Will that example work for a Windows user? Probably not. Keep it more simple. Maybe just asc-pix, pix-png, [do some edits], png-pix, pix-asc. Something like that.
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.
The deadline of the task has been extended with 2 days and 0 hours.
The work on this task is ready to be reviewed.
I not really sure about your example as it's extravenous, i.e., it's not really a use (why would anyone have the ACSII file first unless he converted it, and if that, then why would he have converted it only to have to convert it back again).
Thes sole, main purpose (that I know of, please correct me if I'm wrong) of asc2pix and pix2asc is to allow for transfer to non-Unix machines. We can't ditch the trasfer example.
Since you had a point that the example in it's current from was too localized, I removed the command part and left just the descritpion. This is patch-v4 and tar-v4.
Just in case, I also included patch-v6 and tar-v6 which use the given example.
Please choose which one you like best. Thanks.
I attached the HTML file the make command generated and attached them in the respective tars for easy review. Please tell me if I have to attach the man pages too.
Congratulations, this task has been completed successfully.
Thanks for your patience with the task review yesterday! The latest versions look better. Remember to name your patch files with a .patch or.diff suffix, but one of the latest revisions will get used. You make a compelling case about the network transfer aspect (it could have referenced ttcp for remote transfer).
...
It looks like you only need to complete one more task for the free t-shirt!
3 tasks for a tee, right? That's what it says in the rules. And according to my dashboard, I have already completed 5 tasks.
It says you posted the comment on 10th Jan, i.e., today. So you might have thought I did only 2 tasks (including this one).
Anyways, thanks for all the suport! IRC really rules...
I don't have access to your dashboard, but I gather that you completed tasks for other orgs which is great too. I only knew your count for BRL-CAD.
That was my biggest mistake. HadI concentrated on one project, I might have been moivated enough by the Grand Prize to complete more tasks. But no, I had to just dive in w/o reading the rules. (BTW the other tasks are from Apertium, Sugar and RTEMS).
Thanks for the support. Will try again next year!
You would have needed about 8 tasks to have made our final five consideration. I suspect other orgs are similar.
As GCI comes to a close, we wanted to take the time to say THANK YOU for all your efforts. This comment interface closes after GCI is over, so you're encouraged to join our mailing list where we'll be announcing contributions from GCI participants like yourelf over the upcoming months:
https://lists.sourceforge.net/lists/listinfo/brlcad-news
If you've provided your full name, we'll be sure to credit you in our authorship documentation and you'll see your name in a future announcement. If you contact us at devs@brlcad.org or via IRC, we'll even let you know when your work is integrated and follow up with updates. You're welcome and encouraged to contact us any time, especially if you have a question about how to continue participating in Open Source after GCI is over, but even if just to keep in touch. Take care, be well, and thank you again!