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 | 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 |
I would like to work on this task.
This task has been assigned to Yatharth Agarwal. You have 48 hours to complete this task, good luck!
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?
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.
I preferred switching. I'll work on a-d as it's simpler ;) BTW, couldn't you have updated the previous task also?
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!
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.
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.
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.
The work on this task is ready to be reviewed.
...
Here are the things I did:-
And the results after making were:-
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.
So I modify the g2asc man page to make it only for that command?
It was the man page for two commands (asc2g and g2asc). Now asc2g gets its own man page.
The work on this task is ready to be reviewed.
If the task gets rejected now, can I have a deadline extension of 1 day or so, please?
The deadline of the task has been extended with 1 days and 0 hours.
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 :)
refers to g2asc (in asc2g man-page).
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.
refsect1 xml:id= ...
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.
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).
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.
.
Congratulations, this task has been completed successfully.