Menu
Logged-In As
ACCOUNTNot Logged In
Write manual page documentation (for g-dot)BRL-CAD
Status: ClosedTime to complete:
100 hrs
Mentors: Sean, Mihai NeacsuBeginner
BRL-CAD has hundreds of tools but they're not all documented. We use the Docbook XML system for documentation, which is very much like HTML, but don't worry -- we have LOTS of examples you can follow. Our build system will even validate your file to make sure you didn't make a mistake.
This task entails briefly learning how this geometry converter application works and then writing initial documentation for it. Look at the other g-*.xml files in the doc/docbook/system/man1/en directory for a couple dozen examples.
Once you've created your new file, you'll want to check your work.
- download BRL-CAD from Subversion or use our VM image
- compile BRL-CAD: http://brlcad.org/wiki/Compiling
- create your new file (doc/docbook/system/man1/en/g-dot.xml)
- add it to the build system ( edit doc/docbook/system/man1/en/CMakeLists.txt )
- compile again (make) and make sure it doesn't give an error
- check the compiled version ( in your build directory, run: bin/brlman g-dot)
A lot of little steps, but it's really very easy.
References:- doc/docbook/system/man1/en/g-*.xml
- http://brlcad.org/VolumeIV-Converting_Geometry.pdf
- src/conv/g-dot.c
- doc/docbook/system/man1/en/g-dot.xml -- you'll create this
- doc/docbook/system/man1/en/CMakeLists.txt -- add your new file here
Uploaded Work
| File name/URL | File size | Date submitted | |
|---|---|---|---|
| g-dot.xml | 2.0 KB | December 10 2014 14:50 UTC | |
| CMakeLists.txt | 4.0 KB | December 11 2014 16:16 UTC | |
| g-dot_new.xml | 2.2 KB | December 11 2014 16:16 UTC | |
| my_g-dot_changes.patch | 2.8 KB | December 12 2014 14:17 UTC |
I would like to work on this task.
This task has been assigned to shardulc. You have 100 hours to complete this task, good luck!
Hi,
All the other files have an 'Author' section. What do I put in the 'Author' section for my file? Do I put "BRL-CAD Team"?
Hi shardulc!
Yes, set the author as "BRL-CAD Team". It will help keep it in line with the other files.
The work on this task is ready to be reviewed.
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.
This is a really good start and you seem to have all of the requisite sections. However, your documentation is a little thin. At a minimum, you should have at least reported what the DOT format is for/from. What purpose does it serve? Hint: see the header of src/conv/g-dot.c and read about Graphviz.
Also noticed that the usage statement indicates the .g file argument is optional (it is not).
Did you test adding this documentation to the CMakeLists.txt file and compiling it into html to make sure there are no errors?
You can run these after editing it and submit the resulting my_g_dot_changes.patch file:
svn add doc/docbook/system/man1/en/g-dot.xml
svn diff doc/docbook my_g_dot_changes.patch
I've included the things you mentioned and made sure it compiled, but my patch file only contains the change to CMakeLists.txt because I did not 'svn add' my file before making the changes. So I'm uploading the whole 'g-dot.xml' file and the patch with the single change.
Sorry, meant to say "and *not* the patch with the single change."
The work on this task is ready to be reviewed.
Shardulc, I don't see a patch file submitted. A patch file is generated when you run svn diff. You uploaded the entire CMakeLists.txt file and your g-dot.xml files separately.
You can run svn add even after you've made the changes. Note that a patch file is a specific file format that lets us test your changes easily. If you ran those two commands I mentioned, it should have created a file named "my_g_dot_changes.patch" and that is what I'm expecting you to upload.
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.
Shardul, this looks much better. I was able to successfully apply your changes and they compiled cleanly. Your name has been credited in our release notes and I see that you're already in our AUTHORS file from last year! Welcome back!