Re: [brlcad-users] working on brl-cad tutorials

[Christopher S. M. <br...@ma...>]

Whether someone should grab binaries or sources is very dependent on  
the situation.  You mentioned writing a tutorial, though, and writing  
a tutorial for installing a binary distribution is different for  
nearly every binary platform.  Even if you were to limit the  
instructions to just Linux, the details of installing and running are  
particular to that distribution.

As for missing the README and INSTALL files, that is completely  
understandable and a known limitation of the way binary distributions  
are presently packaged up.  Basically, the binary distributions are  
completed install trees that you are supposed to just copy into  
place.  That usr/brlcad directory gets put into /usr/brlcad and  
you're done.  The alternate approach to that would be to have an  
installer script with top-level documentation files so it is a bit  
more automatic, but that's some repacking and scripting logic that  
would have to be worked on by somebody.

As for coordinating, here is just as good a place as any.  One  
somewhat blunt note, though, is that ideas are cheap.  Doing the work  
to make those changes is much harder and more time consuming.  Your  
suggestions are more than welcome.  Actually making changes to the  
build scripts, installers, website layout, documentation, etc,  
though, are much more valuable contributions. ;-)

As for the x86 binary for Linux, it's mostly just a matter of time  
and effort invested per platform.  We don't make binary releases for  
all platforms all the time because it's a heavy overhead burden.  So  
a given binary platform release get attention as a particular need  
arises or when it's simply convenient/easy to update a platform.   
Ideally, I'd like to get to the point where there are package  
maintainers that create and maintain the binary distributions so that  
the developers can focus more effectively on the code.

If the tutorial's didn't work out the way they are shown in the  
tutorial, then you probably missed a step.  The MGED book in  
particular is meant to be run in sequence as a series of tutorials  
that build upon each other.  You won't be able to proceed very  
effectively skimming or skipping sections.  As for making a picture,  
if you don't see an image by typing "rt" in the command window or  
when using the raytrace control panel, then there may be a problem  
with the default framebuffer (i.e. a problem that cannot be readily  
fixed without recompiling).  There are workarounds (e.g., rt -F/dev/ 
X), but you're better off starting with a clean build made for your  
platform.

A) Sounds like a modeling mistake.  You either have the wrong boolean  
recipe or you were (perhaps unknowingly) displaying the wrong  
objects.  The only way to diagnose would be to know which tutorial  
you were working on and to see your .g file (and ideally see what  
steps you tried to display it).  It's a steep learning curve, which  
is also part why the tutorial series must be followed very  
carefully.  Even after completing the mged tutorial series, you're  
just barely what I'd generally consider a 'novice' modeler.  There  
are engineering practices and lots of other functionality in BRL-CAD  
that has to be mastered to be a proficient novice.

Curious, though,  as I don't recall the tutorials covering fbserv.   
If you're reading suggestions that were sent to another user  
elsewhere, you may be making things much more complex for yourself.   
You shouldn't need to use fbserv.  The tutorial covers using the  
raytrace control panel, which should be all you need to visualize the  
resultant objects.  That said, there is manual page docs for most of  
the command-line commands (like fbserv).  We're working on a major  
overhaul of the mged-specific documentation so that you can have  
manpage-style commands for all of the mged commands too.  That's a  
huge project, though (and help is welcome!).

B) Fantastic.  That will eliminate some of the questions and  
confusions hopefully.

Cheers!
Sean



On Feb 23, 2009, at 6:01 AM, Kyle Pearson wrote:

> Hello again, CSM --
>
> Yeah, i'm familiar with the config/make/make-install dance.  :-)   
> What was confusing for me was that, on the Sourceforge forae, you  
> recommended to one new user that they grab the x86 binaries, rather  
> than the source.  I downloaded the binary tarball, but when i  
> opened it up found only a /usr/brlcad directory tree that i surfed  
> around a bit -- but not very thoroughly, so i missed the README and  
> INSTALL files.  I was thinking that, if it had any, they'd be  
> obviously placed.  I've found them now, though.
>
> Situations like that are the part of what i think i can help with  
> -- helping with overall site design, and efficiency, the insertion  
> of helpful comments here and there.  :-)    How do you suggest we  
> co-ordinate that?
>
> So anyway, back to the story:  i followed the "Linux" button and  
> noticed that the latest version of the binaries seemed to be  
> oriented solely at 64 bit systems -- i didn't see any generic, x86  
> tarballs in the Sourceforge "Linux Downolads" section, except for  
> the binaries from a folder in 2007.  And it was about then i  
> decided to float this e-mail, to see where and how i could add some  
> content to solve things like that -- questions, and weird impasses,  
> that i imagine a lot of would-be users are probably intimidated by.
>
> I got the binaries working, yesterday, and then went through a  
> couple of tutorials (a Sunday afternoon, eh?), but encountered a  
> few problems.  Some of the "unions" didn't get drawn like the  
> pictures i was provided with in the tutorial;  i didn't know if  
> that was convention, a bug, a mistake i made, or what.   The only  
> way i could really tell would be to render it -- i thought -- but I  
> couldn't get the fbserv command working.  I flailed around with it  
> for an hour or two, first as an ordinary user, and then as "root",  
> and wound up shifting my Xserver configuration and diddling it up  
> at the next re-boot.  :-P
>
> So i was never able to get it to render, and had no idea where to  
> go next to figure out what the problem might be.  The tutorial had  
> produced a few figures, but they didn't look like the images on the  
> website and there was an awful lot that i'd discovered along the  
> way -- the GUI interface, the terminal interface, etc -- but had no  
> idea really how to use yet.  In other words, i felt like it was  
> time for another session, and i really had little idea that i was  
> any further along.
>
> That's not a complaint;  it's just that i'm a teacher, and i notice  
> things like that.  So i'd like to find some way to help touch up  
> small things like that.
>
> So -- where i'm at:
>
> A)  Got the binaries properly "installed" and played around with  
> them a bit.  I hit a few snags, though,  in the fbserver command:   
> the display i got wasn't what i was expecting, from the  
> documentation provided.  The "handle" went through the wall of the  
> "cup", and even after the union was performed that anomaly  
> remained.  Was it a display bug?  Was it a bug at all??  Would  
> rendering clear that up?  I had no idea where to go to learn the  
> answers, nor even what to do next.  I tried rendering it, but the  
> fbserv command got in the way.  So i have lots of questions, but no  
> answers, and am eager to figure out the fbserv so i can start  
> rendering things.  :-P
>  -- Is this a problem with the binaries, and -- if so -- then what  
> are the binaries good for?
>      ===>  And i think a copy of this information -- which i'll be  
> happy to type up -- would be good on the Sourceforge download's  
> page, your website, and more conspicuously placed within the binary  
> tarball -- as, say, a "README.brl-cad.txt" file that pops out along  
> with the file-tree.  Not because it's necessary -- but just because  
> it's an easy thing you could do (in the next release, if you wish)  
> that would be a big help.
>  -- If rendering would have helped, then:  are there more reliable  
> commands than fbserv for rendering things?
>  -- If not, and i must use the command (and use it often!), then  
> i'm going to need to learn a bit from you about how to troubleshoot  
> it -- a man page, so to speak -- so i can introduce it properly,  
> and more helpfully.  I didn't find anything on your website, or in  
> the html pages, but i haven't looked at anything else from the  
> binaries b/c i deleted them just now.  :-)  For the compliation.   
> Just below.
>
>
> B)  Since i'm still not sure i can trust the interface, yet -- and  
> since eventually, i'm going to need to do somethign like this,  
> anyway -- i'm going to compile it.  I'll let you know how it goes.
>
>
> At any rate, as you can see:  i'm already at work on the first  
> page, and taking notes.  :-)  Thanks for the patience --
>
> Cheers --
>
> K.
>
> On Sat, Feb 21, 2009 at 11:25 PM, Christopher Sean Morrison  
> <br...@ma...> wrote:
> Kyle,
>
> Hi and thanks for the message!  That sounds like a fantastic idea  
> you have there.  It's actually been on our to-do list to have a  
> succinct "introduction to BRL-CAD" that covers installation and  
> basic use.  For coaching you, I'd be happy to help you one-on-one  
> via e-mail.  I would suggest, though, that we talk on the brlcad- 
> users mailing list (cc'd) since that will afford others the  
> opportunity to help you too.  That can be particularly useful for  
> those times when I'm overloaded and may possibly give you (and  
> others) more breadth of an answer to questions as they come up.   
> The brlcad-users mailing list can be joined [1] here:
>
>  [1] https://lists.sourceforge.net/mailman/listinfo/brlcad-users
>
> As for installation, the steps are usually very specific to the  
> platform you're installing on except for installing from a source  
> code release (where it's the same for most platforms).  If you're  
> on Linux, that's what I would say you should start with just to  
> make the steps the easiest to make generic (at least in terms of  
> contributing a tutorial).  So the first step would be to go to  
> http://brlcad.org and selecting "Download" off the menu, then  
> selecting the Source link.  That will take you to [2] a page on  
> Sourceforge that has all source downloads listed.  Download one of  
> them and unpack the tarball.
>
>  [2] https://sourceforge.net/project/showfiles.php? 
> group_id=105292&package_id=113368
>
> Once you unpack the sources, like most open source packages, there  
> are a couple "standard" files that you should read.  That would be  
> the [3] README and [4] INSTALL files.
>
>  [3] http://brlcad.svn.sourceforge.net/viewvc/brlcad/brlcad/trunk/ 
> README
>  [4] http://brlcad.svn.sourceforge.net/viewvc/brlcad/brlcad/trunk/ 
> INSTALL
>
> While the exact instructions and options will vary slightly from  
> release to release and will depend on your platform, the basic  
> compile-and-install steps are pretty much the same.  You prepare  
> the build system "autogen.sh", you specify compilation options with  
> "configure", you run "make" to build everything, and then "make  
> install" to install everything.  For purposes of a tutorial, the  
> steps that will generally work best for most are:
>
> sh autogen.sh
> ./configure --enable-all --without-ogl --enable-optimized
> make
> sudo make install
>
> To understand everything that is spelled out there requires reading  
> through most of [3] README and [4] INSTALL but is pretty common for  
> most Linux source installations.  That should get you started.   
> Assuming everything compiles and installs cleanly, the [4] INSTALL  
> file covers how to test the installation to make sure everything is  
> okay.  Once that is done, our existing [5] Documentation then  
> becomes invaluable.  I'd suggest going through the list one at a  
> time in order going down the list.
>
>  [5] http://brlcad.org/wiki/Documentation
>
> The second document, "Introduction to MGED" is a very detailed  
> series of tutorials that aim to get someone familiar with the  
> basics of modeling using BRL-CAD.  Please don't hesitate to write  
> back with any questions or clarifications.
>
> Cheers!
> Sean
>
>
>
> On Feb 21, 2009, at 5:00 AM, Kyle Pearson wrote:
>
>> I'm a teacher, and have done a bit of technical writing, and i'm  
>> also interested in learning brl-cad -- but i've never used CAD  
>> software and have no idea where to begin sifting the mountain of  
>> your documentation to get to design even a simple object (right  
>> now, the project is a fine-wood bread-maker's cabinet).
>>
>> So i've been around Linux for a few years, and have always been  
>> interested in contributing something, but never really saw an  
>> opportunity like this one.  I'd love to help y'all write up some  
>> basic introductions to brl-cad;   i could learn a lot, get some  
>> free coaching on its installation, usage, and whatnot, and then  
>> write up what i learn as tutorials.
>>
>> We could start with "installation", and go from there.  :-)
>>
>> I'm familiar enough with Linux systems that, in a small-business  
>> situation, i could probably pass as an adequate sysadmin.  I live  
>> in Taiwan, though, and those guys are a dime-a-dozen.  I have  
>> virtually no familiarity with coding applications, nor with full- 
>> featured programming languages -- just enough to get by, and no more.
>>
>> I think my abilities are well matched to this task, and would be  
>> happy to lend a hand -- at least for a few months.
>>
>> So if y'all would like to set me up with a contact who'd be  
>> willing to patiently coach me through the fundmentals, then i'd be  
>> more than happy to write up the lessons i receive as tutorials,  
>> hyper-link them, and construct a basic set of introductory  
>> materials that people can use to get started.
>>
>> K. Pearson
>>
>> -- 
>> Pray for Gaza, and the brave, beleaguered Palestinians.
>>
>> Please avoid sending me Word or PowerPoint attachments.
>> See http://www.gnu.org/philosophy/no-word-attachments.html
>
>
>
>
> -- 
> Pray for Gaza, and the brave, beleaguered Palestinians.
>
> Please avoid sending me Word or PowerPoint attachments.
> See http://www.gnu.org/philosophy/no-word-attachments.html
> ---------------------------------------------------------------------- 
> --------
> Open Source Business Conference (OSBC), March 24-25, 2009, San  
> Francisco, CA
> -OSBC tackles the biggest issue in open source: Open Sourcing the  
> Enterprise
> -Strategies to boost innovation and cut costs with open source  
> participation
> -Receive a $600 discount off the registration fee with the source  
> code: SFAD
> http://p.sf.net/sfu/ 
> XcvMzF8H_______________________________________________
> BRL-CAD Users mailing list
> brl...@li...
> https://lists.sourceforge.net/lists/listinfo/brlcad-users