Write a manual page for MGED's ''brep'' commandBRL-CAD
Status: ClosedTime to complete: 72 hrs Mentors: SeanTags:

BRL-CAD's MGED geometry editor provides hundreds of commands. One of those commands for manipulating and visualizing geometry is the ''brep'' command.

This task involves writing a manual page for that command in the Docbook XML format. There are lots of examples to follow.

References:

  • doc/docbook/system/mann/en/*.xml
  • http://brlcad.org/wiki/Documentation (contains intro to mged and cheat sheets)
  • bin/mged (you'll need to run this to use the ''brep'' command)
  • bin/csgbrep (will create a slew of 'brep'/nurbs objects for the ''brep'' command)

Code:

  • doc/docbook/system/mann/en/brep.xml (you write this)
  • doc/docbook/system/mann/en/CMakeLists.txt (you edit this)

Running ''make'' in a build directory will compile your documentation into html and man page format so you can validate the syntax and formatting. See [[Compiling]] for help.

Uploaded Work
File name/URLFile sizeDate submitted
brep xml doc.txt2.1 KBDecember 07 2013 23:06 UTC
CMakeLists.txt4.1 KBDecember 09 2013 23:42 UTC
brep.patch2.0 KBDecember 12 2013 14:26 UTC
my.patch367 bytesDecember 15 2013 01:52 UTC
myfinish.patch2.7 KBDecember 17 2013 00:14 UTC
Comments
Alexon December 5 2013 12:51 UTCTask Claimed

I would like to work on this task.

Gauravjeet Singh on December 5 2013 12:53 UTCTask Assigned

This task has been assigned to Alex. You have 72 hours to complete this task, good luck!

Alexon December 5 2013 23:36 UTCbrl-cad tasks

I want to participate in more BRL-CAD task as they interest me but feel like i dont have enough skill in the area required for the task alot of the time. I was wondering how i could learn more about the system and gain a wider knowledge of how the software is used so i can participate in more tasks?


Also, where are the links about docbooks 'doc/docbook/system/mann/en/brep.xm' reffered to in task description leading to? the dont lead to anywhere on my computer or a link on the internet? 


i get what an xml document is but dont understand these docbook links given?

Alexon December 7 2013 23:06 UTCReady for review

The work on this task is ready to be reviewed.

Melange on December 8 2013 12:53 UTCNo more Work can be submitted

Melange has detected that the deadline has passed and no more work can be submitted. The submitted work should be reviewed.

Sean on December 8 2013 15:39 UTCDeadline extended

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

Sean on December 8 2013 15:55 UTCglad to hear it

Hi Alex!


Glad to hear that you're interested in working more on BRL-CAD, but don't worry at all about your skills or time.  There's ample skills for all skill levels and plenty of time.  As for gaining wider info about BRL-CAD, we recently created a book for contributors on just that which you can read online here:  http://www.flossmanuals.net/contributors-guide-to-brl-cad/


The file links refer to paths in our source tree, which you can checkout from our Sourceforge subversion repository (you can find this easily with a google search or via our website) or you can use the virtual disk image we've prepared as described here: http://brlcad.org/wiki/Deuces


 

Sean on December 8 2013 16:12 UTCreason for more work

The reason I marked this for more work is so that you can submit your work in proper patch format, integrated into our build system.  You'll need to make an edit to the doc/docbook/system/mann/en/CMakeLists.txt file too, and once you do, you can run "svn diff my_patch.diff" to create a patch file.  That will be the file you submit.


 

Sean on December 8 2013 16:12 UTCTask 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.

Sean on December 8 2013 16:14 UTCin case you're wondering

If you know what you're doing, this last step should take all of 2 minutes.  It might take you a couple hours to figure out how to get our sources, compile, make your changes, compile again to make sure it works, then generate the patch file that you submit.  Ask questions if anything comes up and you're stuck for more than an hour.


 

Alexon December 8 2013 18:25 UTC

Thanks for the detailed feedback answering my questions. I have found myself stuck though


I have installed brl cad software from the brl cad website a few weeks ago, there is no brl-cad program, just archer, mged and rtwizard.


I have tried searching for the 'source tree' all over sourceforge on the brl cad section. im am not sure of the doc/docbook/system/mann/en/CMakeLists.txt but have managed to find this: https://svn.code.sf.net/p/brlcad/code/brlcad/trunk/CMakeLists.txt 


Which i think is the same thing but i am not sure how or what to edit on it.


Where abouts do i enter the  "svn diff my_patch.diff" command you mentioned. i tried reading through the http://brlcad.org/wiki/Patches but wasnt sure what i had to install. It says i should install subversion which i attempted but it asked for a host/server name and was unsure what to enter. (couldnt leave it blank).


What is the 'source tree' so i can navigate to the docbook links refered to. ?


Where do i enter the "svn diff my_patch.diff" command for creating this patch?


What do i edit for the 'CMakeLists.txt' ?


 

Alexon December 9 2013 23:21 UTCfound out

I have found out about the source repository and can now see all the docbook links reffered to. I found the CMakeLists.txt and have added the 'brep.xml' name to it in its alphabetical place. 


I am still having trouble creating the patch.


I have brl - cad installed but do not no where the "svn diff my_patch.diff" command comes into it. I have tried installing sub version for windows and the first version, asked for a server name (it would not take localhost) and i wasnt sure what to put.


I tried installing another version from the list but it was just a mixture of .exe and .dll files (there was no setup program). I also installed 'Cmake' as i think that may be needed but that is also a mixture of files in a winrar document; Overall i am confused on how to make this 'patch' file.? and what i am suppose to do with the CMakeLists.txt?

Alexon December 9 2013 23:38 UTC

I now have subversion installed but still have the same problems

Alexon December 9 2013 23:41 UTCReady for review

The work on this task is ready to be reviewed.

Alexon December 9 2013 23:43 UTC

I know the patch file hasnt been uploaded but i uploaded the 'cmakelists.txt' to extend the time so you could get back to me on my queries.

Sean on December 10 2013 08:18 UTCDeadline extended

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

Sean on December 10 2013 08:18 UTCTask 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.

Sean on December 10 2013 08:24 UTCprevious comment

Alex, I responded to your forum message and apologies on the belated reply, but glad to see you're making progress.  Creating a patch on Windows is a bit cumbersome with most graphical interfaces, so I would suggest using our Virtual Disk image download -- it's preconfigured and ready to go, much more simple.


That said, you can look around the web for tutorials on creating patches on Windows as there are hundreds.  Here's one, for example: http://make.wordpress.org/core/handbook/working-with-trac/submitting-a-patch/


Basically, you're going to add your brep.xml file to your checkout, edit the CMakeLists.txt file, and tell Subversion to create a patch file from those edits.  If you were on linux, that's exactly three commands.


Our repository URL for checkout is https://svn.code.sf.net/p/brlcad/code/brlcad/trunk


We usually tell it to name the checkout directory "brlcad" (otherwise it will default to "trunk").


 

Alexon December 10 2013 23:06 UTCThanks

Thanks for the reply and extend on time. i will do my best to create this patch and Cmakelists.txt

Alexon December 12 2013 15:18 UTCcreate patch

i have created a patch file and have created a ticket for it on sourceforge.

Alexon December 12 2013 15:36 UTCReady for review

The work on this task is ready to be reviewed.

Melange on December 12 2013 15:43 UTCNo more Work can be submitted

Melange has detected that the deadline has passed and no more work can be submitted. The submitted work should be reviewed.

Sean on December 13 2013 06:33 UTCDeadline extended

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

Sean on December 13 2013 06:33 UTCTask 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.

Sean on December 13 2013 06:36 UTCnot a patch file

Alex, what you submitted is not a patch file.  Please see my previous reply.  Ask questions if you do not understand something or don't know what to do.  Don't guess.


There are literally thousands of tutorials around the web on how to make a patch file.  I suggest you follow our step-by-step instructions, which should take less than an hour even at a slow pace:


http://brlcad.org/wiki/Deuces#Getting_Started


http://brlcad.org/wiki/Deuces#When_You.27re_Done


 

Sean on December 13 2013 06:37 UTCif you need more time

If you need more time, just ask.

Alexon December 14 2013 01:13 UTCmore time please

Please could i have some more time on this task, i think i know what to do now and am currently on the virtual disk image. The 'make' command is taking a long time and has not yet reached %100.


The only question i have is what exactly am i suppose to do with the 'cmakelists.txt'?

Alexon December 14 2013 01:42 UTCextending time

Currently i have just entered the 'svn co' command to the trunk link of the repository (with brlcad.edit written on the end)


At the moment the command line is loading all the files and once thats done i will make my changes, once the command line is done loading the files from the repository link what do i actually do?


from my understanding i think i add the brep.xml file, the cmakelists.txt and then make a patch file. 


but what does this actually involve?


I am going to mark the task as complete so it doesnt end before you get back to me

Alexon December 14 2013 01:43 UTCReady for review

The work on this task is ready to be reviewed.

Sean on December 14 2013 02:40 UTCDeadline extended

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

Sean on December 14 2013 02:43 UTCcmakelists.txt

Did you read the CMakeLists.txt file?  It should be somewhat obvious if you read through and just observe the basic structure in that file.  There's a list of xml files.  You've created a new xml file.  You add your file to the list of xml files.


You'll do that *after* you've successfully compiled first with "make" just to make sure everything builds fine.  Then you make that edit and run "make" again.  You should see it "build" your brep.xml file into other formats (e.g., html) and do some basic validation to make sure you didn't miss anything.


If you're using the virtual disk image, it already contains a source checkout so you wouldn't need to run "svn co".  You'd just run "svn up" to update it to our latest sources, then make, then your edit, then make again.  Make sense?


 

Sean on December 14 2013 02:43 UTCTask 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.

Alexon December 14 2013 15:33 UTCpatch file created

ok i have now created a proper patch file (it contains details of the changes made with the 'brep.xml' and cmakelists.txt.


I will now just follow the rest of the instructions at the bottom of the Deuces page. (brlcad.fresh commands etc)


I will also create a new ticket of the proper patch file

Alexon December 15 2013 01:50 UTCuploaded patch file

i have uploaded the patch file which i think is correct .


Is there anymore i need to do?


I will make a ticket on sourceforge of it, and have applied the patch in the command line.

Alexon December 15 2013 23:24 UTCReady for review

The work on this task is ready to be reviewed.

Melange on December 16 2013 07:58 UTCNo more Work can be submitted

Melange has detected that the deadline has passed and no more work can be submitted. The submitted work should be reviewed.

Sean on December 16 2013 08:20 UTCsingle patch file

Almost there, Alex.  The patch file you uploaded only includes the CMakeLists.txt file change, but not your new manual page.  You need to run this first to let svn know about your new file:


svn add doc/docbook/system/mann/en/brep.xml


Then you should be able to run svn diff to get the complete patch.


 

Sean on December 16 2013 08:20 UTCDeadline extended

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

Sean on December 16 2013 08:20 UTCTask 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.

Alexon December 17 2013 00:15 UTCReady for review

The work on this task is ready to be reviewed.

Sean on December 17 2013 03:12 UTCclose enough

Alex, that is a valid patch file, hurrah!  You've certainly made a lot of progress and put effort into accomplishing this task so I'm going to mark it complete.


Note, however, that there are/were still several issues.  There are numerous errors in the actual XML and it wouldn't generate documentation correctly because it failed validation.  If you would have compiled BRL-CAD, you would have seen the error.  There are also a number of problems with the documentation content (numerous spelling, grammar, and prose errors).  The brep command has many options, and you documented none of them.


That said, I fixed them in the quickest way possible for the purpose of closing out this task because of your extended efforts.  I'll be creating a follow-on task to improve the manual page if you are interested in taking this to completion.  You're also welcome to try a different type of task to try a different challenge.


Regardless, nicely done and thank you again for your efforts.  If you provide your full name, we'll credit you accordingly in our authorship documentation (which already has a note for this work).


 

Sean on December 17 2013 03:14 UTCTask Closed

Congratulations, this task has been completed successfully.

Sean on December 17 2013 03:21 UTCfollow-on task

A follow-on to this task has been posted.  http://www.google-melange.com/gci/task/view/google/gci2013/6343330480783360


 


The above patch was first commited in r58965 and updated in subsequent commits.


 

Sean on December 17 2013 03:25 UTCfull name

Never mind about providing your full name -- I found it from your other GCI tasks.  Thanks again.

Alexon December 17 2013 08:03 UTCfollow on task

Thanks for editing my work sorry there were some errors, i will checkout the follow on work.