Posted on

Geeking Out With Netbeans and PHPDoc

I’ve been playing with phpDoc and NetBeans a lot lately.  I’ve found that having well documented code using the phpDocumentor 2 format makes for a much more efficient coding environment.   For one thing, if you have NetBeans setup properly and are using PHP classes that are fully documented, writing a line of code is as simple as typing a few characters.  NetBeans will find the objects you are looking for and list the properties and methods as you type.

That makes for some fast coding when typing something like $this->plugin->currentLocation->MakePersistent().  When everything is setup properly and the classes are properly documented I can type $t<tab>p<tab>c<down><tab>M<enter>.    While it may look like a lot of typing when spelled out essentially I am typing “$ttptcdtme”, or 10 characters instead of somewhere around 70.    Being 7x as efficient when writing thousands of lines of code is a HUGE bonus.

GitHub Markdown Docs for Code

Auto-complete shortcuts alone is one good reason to use a strong IDE like NetBeans along with a good code commenting/documentation solution like phpDocumentor2.   However tonight I found a cool new trick that I stumbled upon while trying to generate code documentation via GitHub.    I had learned a couple of weeks ago that I could use the command-line PHPDoc tool and a open source GitHub project called PHPDocMD to convert my code comments to XML and convert that to markdown (MD) that GitHub likes.   It creates OK results that are out on the public code repositories at Github.

So what is that new trick?  Well, there are 2 distinct parts.

Autogenerated HTML Docs for Code

Turns out there is a plugin for NetBeans that I’ve been ignoring.  For some reason I just happened to figure out that the “Generate Documentation” menu that appears when I right-click on a project in NetBeans actually has some use.

Yeah, I’m slow like that sometimes.

Turns out that under that menu is a submenu that has “ApiGen” and “PHPDoc” listed there.    Interesting.    That could be useful.

I went to the project, right-click, and select properties.  Sure enough, there is a setting for “PHPDoc” and it asks for a destination directory.  Basically asking “where do you want me to dump all the auto-generated documentation for your project?”.    Well it turns out that during my journey toward publishing code documentation on GitHub with MD, I had cloned the GitHub documentation repository to a local path on my development system.   I already had a folder full of code docs for my main plugin as well as several add-on packs.   So I pointed the output for my Netbeans “PHPDoc” setting to go there.

I go back, right click on the project, and select the Generate Documenation/PHPDoc.

Sure enough, NetBeans crunched my code comments and a few minutes later my Firefox browser window pops open and I see a pretty darn cool HTML site on my local box that has a full navigation menu for all of the classes I am using in my project, the properties, the To Do lists from my comments and more.  All this created because I’ve been taking a bit more time to fully comment the code.  Nice!

Settings Up For Auto-Publishing

Ok, so now on my dev box I have some pretty nice code docs that I can generate with a couple of mouse clicks.   That is helpful with a large project with multiple add-on packs.   But then I start thinking, why just keep it local?   The code is open source.  I have other developers that want to learn how to tweak the code for their own purposes.  I have third party developers looking for documentation and examples on how to do things so they can write efficient add-on packs.    Why keep the info all locked up on my dev box?

Well, I learned a neat trick a couple months ago with NetBeans.    I can have a local git repository on my development system but setup NetBeanswith a new “remote source” project.

So here I am with my commented code in my WordPress plugin directory that is fully commented and connected to a GitHub repository.   In another “docs only” directory outside of WordPress I have my PHPDoc generated HTML and MD files that I was previously only publishing to GitHub Wiki Pages, but now thanks to NetBeans I am also surfing locally on my dev desktop.     I realize I can auto-publish these code docs to my public website.

I create a new NetBeans project right next to my plugin code project.   I call it “store-locator-plus-codedocs” and set it up as a new PHP Remote Source project.   I tell it the local source on my box is the folder that I was storing the PHPDoc and MD files in for GitHub, which now contains my NetBeans-generated HTML files as well.    For a remote location I tell it to use my SFTP connection to the Charleston Software Associates website.  I jump on my website and make sure there is a new codedoc directory with a blank readme.txt file there.  If you don’t have SOMETHING for NetBeans to download from the remote source it thinks you screwed up and won’t continue…. minor flaw IMO, but easily remedied.    I then click OK.  It shows me the readme.txt with a checkbox to download it.    Click OK and BAM… there is a new project with the blank readme.txt plus all of the MD and HTML documents that were already on my local dev box.

OK, so kind of “so what” at this point, but here is where it starts getting cool… at least from a geek perspective.

Push The Initial Content

Now I need to “seed” the public website with the already-created content.   In NetBeans it is easy enough. Just highlight all the files in the project, right click and select upload.    Within a few minutes the entire HTML sub-site is uploaded to the server.   Just like any FTP program.   Nothing to it.

However now if I make any changes to those file with the editor two things happen, it saves a local copy on my dev box and it auto-publishes that updated to the live server in near-real time.    Since my local dev box has version control via GitHub, I can also quickly commit and push those edits also from inside NetBeans and make sure they are saved to the code repo.

But… I’m not going to ever edit those docs by hand.  They are auto-generated code documents that come from my well-formatted comments.  So the RIGHT way to edit them is to continue cleaning up and augmenting the code comments to make sure they are PHPDoc compliant.

So that is kind of cool.  My code docs are now auto-posting to my live server, saving on my dev server, and are one click from being saved and committed back to GitHub.  I can even add on more step and create a second copy in MD format for publication right next to the source code on GitHub.

But this is what really made me think “shit this is kind of cool”…

Auto-Publishing Code Comments

So I have all this stuff setup, my code project and my documentation project are both open at the same time in Netbeans.    I forget all about it as I start getting back into code writing.     I edit a method for one of the add-on packs and of course I go and update the comments about that method to reflect the latest changes.  I see another comment that is not complete and fill that out.

Save the code.  Commit the code so it publishes to GitHub.

A few more edits to code and comments later I decide… let’s generate the documentation before I sign off tonight…

I right click on my code project and select “generate documentation”.

Auto-magically the documentation project updates itself.   It saves a copy locally to my dev box with the new docs in place then auto-publishes to the public website with no intervention on my part.   As I setup the rest of my plugins with this system you will be able to find all the code docs on the bottom of the Technical Docs page on my site.   You can see my first auto-published work for Tagalong here, though I’m nowhere near done cleaning up the comments and naming conventions on my method to make this all “gussied up” for public consumption, but it’s a good start.

Maybe I’m just extra-geeky, but I thought that was cool… especially when the code docs actually look pretty darn good IMO, especially since they were created from nothing but /** This method does something.  @var string $this – does that **/ comments in the code.

I also know that with a few lines of script I can not only save locally and publish nice looking docs to my public site but also commit the code back to the GitHub repository while auto-generating the duplicate MD docs for the GitHub Wiki.

Yeah, I’m a Code Geek… and I’m not ashamed to admit it.

Posted on

Using Netbeans

Chase introduced me to Netbeans a couple of months ago.   It looked cool, but as with any dev tools there is some inertia involved in switching to a new editor.

I’ve been using Netbeans on my Linux dev box for about a month now.  While there are some quirks and some problematic areas with Netbeans, overall I have grown to like it more than jEdit, gvim, WinEdit and a handful of other code editors.    It is well balanced between the powerful, but often way to “heavy”, Visual Studio platform and the weaker editors like jEdit.
My favorite features I’ve come to discover & use on regular basis:

“Projects”

Netbeans will create projects based on current source directories.  Tell it the basic project type, such as PHP, and the starting file.  It tries to be intelligent about the structure of your code by doing semi-intelligent crawling.  It does a decent job.  The thing I really like about this is now that I have a dozen source directories setup as projects I can use the other tools (see find below) to locate stuff wherever it may reside.

“Find In Project” (ctrl-shift-f)

Netbeans will build a project based on a source directory you specify.  It crawls the source and builds a semi-intelligent index, which is a nice feature for “object browsing”.   However this quick search tool is my “go to” for locating “stuff”.    You can easily setup include/exclude patterns using system tools like “exclude this folder” or regular expressions.   The regex include/exclude is easy to use and super-powerful.     This same tool allows you to search “all projects”, “all open projects” or just the current project.

“Navigate”

Highlight a function or variable and right-click.  Use Navigate to find the definition or all occurrences (usage) of the same variable/function/thing-a-ma-bob.   Very nice and cuts down on my “find in project’ searches, especially when I want to modify a definition.

“Smart Complete”

I’ve not seen this in a decent PHP editor before, but it works much like the Visual Studio tool.  Start typing a method/function name and it pulls up all possible methods/functions and their property variants.  If you have optional params it lists those as different variants.  If your commenting on the declaration is well formatted it will also show you the description of the function, what the parameters are meant to do and more.     Scroll, pick one of the prototypes from the list and press enter and the call is put into the inline code, press tab to jump to and replace each param.

“Commenting”

This kind of goes with “Smart Complete”.    It took me 6 weeks of using Netbeans to find this because I NEVER write the code first then add the comment block.  I always put a stub comment first, then go back and fill it in.    I happened to paste in a function from elsewhere that had no comments, went above it and typed “/**”.   Netbeans automatically created a comment block with all the params listed.  That was cool.
You can learn more about auto-created comments and auto-completion here:

Summary

So I’ve grown to really like Netbeans.    Yes, it has some issues but overall the benefits outweigh the problems.
I know Eric has a plethora of Emacs tips & tricks he’s shared over the years.   What about others?  Do you have a favorite editor or IDE?   What are the cool tricks you’ve found?   Or if you use Netbeans, what other shortcuts have you discovered to help you manage/write code?
Posted on

Connect To Your Database With Emacs

The recent Emacs post made me think of a useful SQL trick I recently learned that I wanted to share. Emacs refers to different SQL engines as ‘products’, e.g. MySQL, SQLite, and so on. You can connect to an SQL database through Emacs but you have a call a different command based on the product.

An easier way to do this, as of version 24, is to use the keyboard shortcut C-u C-c TAB when viewing an SQL document. This will prompt you first for the product, and then for any connection information. So if you are working with an SQLite database you can press C-u C-c TAB, type sqlite, and then the filename of the database; that will open an interactive window connected to the database. Or if you are using PostgreSQL then Emacs will ask for a username, port, etc. The supported products are:

  • db2
  • informix
  • ingres
  • interbase
  • linter
  • ms
  • mysql
  • oracle
  • postgres
  • solid
  • sqlite
  • sybase

I don’t even know what some of those are…

Anyways, sometimes I find this faster than opening a terminal if I need to run some test queries or copy output into a document. (This is very useful with SQLite’s .mode html command, which will print the results of queries in <table> form.)


ejmr
南無妙法蓮華經

This article was originally posted on “The List” by EJMR.

Posted on

Ubuntu – No Audio When Playing Videos

I recently tried to play a video on Ubuntu 10.04, but got no audio because of missing a Windows Media Audio codec. My video player tried to automatically find a suitable plugin and failed. So here’s how I fixed it by hand.

Step One: Update mplayer

The version of mplayer that comes with Ubuntu is behind the times.
But that’s easy to fix.

    $ sudo add-apt-repository ppa:rvm/mplayer
    $ sudo apt-get update
    $ sudo apt-get upgrade mplayer

Bam. Done. Also why not install smplayer while you’re at it—has a much better interface in my opinion.

*Note:* If you prefer to use something else like vlc then upgrading may not be necessary. Check the documentation for your preferred movie player to see about its WMA support.

Step Two: Discover the DLL You Need

This is easy: just try playing the file from the command line.

Something like

    $ smplayer legitimate_copy_of_a_movie_i_totally_own.wmv

If you see a ton of output, and hear no audio, then you are missing a library. Thankfully (s)mplayer will tell you exactly what this library is called; just look in the output for the name of a `.dll` file mentioned in conjunction with audio.

Step Three: Add the DLL

Get on your favorite search engine, enter the DLL, and find a copy to download.

Whatever DLL you need, take it and put it in the directory `/usr/lib/codecs`. The directory probably does not exist, so create it first, of course. Video players will automatically look there for the DLLs they need.

After that, you should all be set. That’s how I was able to get audio out of Windows Media Player 9 files. Hope it helps you too.

Posted on

Word 2007 Blank Pages Between Chapters

While working on a documentation project for a client we ran into a unique problem.  According to good technical writing practices, you always want chapters to start on an odd page.  This puts new chapters on the right-hand page of a bound book.  You also want to ensure that any preceding blank page is not 100% blank, most standards dictate at least a footer with a page number and possibly a header with the title of the prior chapter (old school methods were to put a “This page intentionally left blank.” message on the preceding blank page, which is one of my favorite all time ironies).  After digging around for hours (OK, maybe 10 minutes) I found the solution to this blank page problem.

It turns out that when you are forcing pages to start on an odd page # for things like a chapter to always appear on the right side of a bound book, you end up with blank pages preceding some of those pages.  That is just how Word works.  If your previous chapter ends on an odd page, it automatically inserts the blank so that the new chapter starts on the odd page as well.   However, it is clearly documented that Word does not put ANYTHING on that page, not even headers or footers.  There is not setting that says “carry headers/footers over to blank pages”.

The official Microsoft solution… use the hard page break, CTRL-ENTER just before the odd-page-break whenever you want to force Word to insert the header/footer on the blank page.

http://support.microsoft.com/kb/264905

The problem with that solution?  If your document changes the CTRL-ENTER will force a new page ALWAYS.  If your existing work is updated and the prior chapter now pushes up from ending on an odd page to ending on an even page, guess what?   You get TWO BLANK PAGES… one with a footer (the forced blank page) that is now an odd page # with a footer, and an even page with NOTHING… the exact problem you were trying to solve the first go-around.

Bottom line, to get technical documentation standard page footers AND chapters starting on the right-hand page, you will constantly need to scan & manually revise the page breaks in the document every time you update the content, especially if you lengthen any chapter.

Wonderful.  Thanks Microsoft, thank you very much.  Why even provide “odd page break”?  Might as well keep things simple and force 100% manual management of pages with CTRL-ENTER throughout.   Grrrrr… sometimes working with these high tech tools can be so aggravating.     20+ years of MS-Word development and they still don’t have an elegant solution for this common problem.  It was even documented as far back as 2000 and Microsoft had enough inquiries to have written TWO knowledgebase articles about it back then.

Posted on

PuTTY Window Name Trick

We’re working with Amazon EC2 instances on a regular basis these days and my current preferred method of connecting to the command line is via PuTTY.  It is a fairly simple program that gets the job done (though I prefer SecureCRT for a more robust terminal app).  However, the Amazon host names are setup to be the internal DNS name for the server.   This is usually something useful like domU-11-22-33-44-A1-ST-ea-ks-au-ce-ha-ha.

While the hostname itself is not usually a problem, nor is the fact that PuTTY sets the default window title to the hostname, it gets to be confusing when you have more than 2 terminal windows open and are flipping between them on a regular basis.  I often found myself on server A when I thought I was on server B.   Luckily PuTTY lets you name the windows, or so I thought.   In your session creation window you can go to the Window/Behaviour Category and set the window title.   That works great.

Until you login.

The problem is that many Linux servers shoot back an encoded “change window title” command.  While this is often useful if your server hostname is something like “MainServer” and “SecondaryServer”, it really sucks for the aforementioned internal DNS names that some whacked-out crack addict came up with for Amazon EC2 instances.    However, after a little “Googling” (don’t even get me started on how they pwned me by blanking out a Google Sites page tonight) for a few minutes, I  came across the “fix” which isn’t really explained well on the PuTTY FAQ page that came up (you can disable terminal response to change title messages from the server). The fix is a two step process:

1) Go to the aforementioned Window/Behaviour/Window Title setting and put in a title that makes sense to you.

2) Go to the Terminal/Features settings and check off the Disable remote-controlled window title changing box.

You are now good to go with window titles that makes sense for your EC2 instances, or whatever other PuTTY session title you want to change.

Posted on

Microsoft .Net Framework

Cyber Sprocket and the .Net Framework

Many of the Cyber Sprocket desktop applications require the Microsoft .Net Framework.

Older windows computers do NOT have the .Net Framework installed. All new windows programs that access the Internet will require the .Net Framework, and thus it is a component of newer Windows operating systems. If you are running an older PC and have Windows updates enabled you most likely have the .Net Framework. New XP, Vista and Windows 7 computers come with the .Net Framework by default.

If you are not sure if you have the .Net Framework installed you can skip this step and just begin the program installation, it will tell you if you need to install the .Net Framework during the setup process.

The .Net Framework has several versions, the minimum version required for most Cyber Sprocket applications is version 1.1. We recommend installing version 2.0.

What Is The .Net Framework?

The Microsoft .NET Framework is a software component included with the Microsoft Windows operating system. It provides a large body of pre-coded solutions to common software development requirements, and manages the execution of programs written specifically for the framework. The .NET Framework is intended to be used by most new applications created for the Windows platform.

The pre-coded solutions that form the framework’s Base Class Library cover a large range of programming needs in areas including: user interface, data access, database connectivity, cryptography, web application development, numeric algorithms, and network communications. The class library is used by programmers who combine it with their own code to produce applications.

Programs written for the .NET Framework execute in a software environment that manages the program’s runtime requirements. This runtime environment, which is also a part of the .NET Framework, is known as the Common Language Runtime (CLR). The CLR provides the appearance of an application virtual machine, so that programmers need not consider the capabilities of the specific CPU that will execute the program. The CLR also provides other important services such as security mechanisms, memory management, and exception handling. The class library and the CLR together compose the .NET Framework.

The .NET Framework is included with Windows Server 2003, Windows Server 2008 and Windows Vista, and can be installed on most older versions of Windows.

.Net v1.1

If you do not have the .Net Framework already installed on your PC you can obtain the program in one of two ways:

  1. Download the dotnetfx.exe file from Cyber Sprocket, then double click the dotnetfx.exe that has been downloaded.
  2. Visit the Microsoft Download Center to download the latest version.

.Net v2.0

If you do not have the .Net Framework already installed on your PC you can obtain the program in one of two ways:

  1. Download the dotnetfx.exe file from Cyber Sprocket, then double click the dotnetfx.exe that has been downloaded.
  2. Visit the Microsoft Download Center to download the latest version.

Issues With Microsoft .Net Framework

Repair May Be Needed

The .Net Framework Indicates Repair May Be Needed
The following is documentation from the Microsoft .Net Framework:

Installation Repair

You may need to repair your installation of the .NET Framework after upgrading your operating system or if the system becomes corrupted.

To repair the .NET Framework

  1. Obtain the original installation source. For example, if you installed the .NET Framework from CD or DVD, insert the disk. Or, if you downloaded the .NET Framework, download again and choose to save to disk. If you installed from a network share, reconnect.
  2. On the Start menu, choose Run.
  3. For Windows 98 and Windows Me type:
    command

    For Windows NT, Windows 2000, Windows XP or later, type:

    cmd
  4. In the command window, type the following:
    n:<Installation Source>dotnetfx.exe /t:%temp% /c:"msiexec.exe /fvecms %temp%netfx.msi"

    For example:

    d:dotNetFrameworkdotnetfx.exe /t:%temp% /c:"msiexec.exe /fvecms %temp%netfx.msi"

To repair a .NET Framework Language Pack

  1. Obtain the original installation source. For example, if you installed the .NET Framework from CD or DVD, insert the disk. Or, if you downloaded the .NET Framework, download again and choose to save to disk. If you installed from a network share, reconnect.
  2. On the Start menu, choose Run.
  3. For Windows 98 and Windows Me type:
    command

    For Windows NT, Windows 2000, Windows XP or later, type:

    cmd
  4. In the command window, type the following:
    n:<Installation Source>langpack.exe /t:%temp% /c:"msiexec.exe /fvecms %temp%langpack.msi"

    For example:

    d:dotNetFrameworklangpack.exe /t:%temp% /c:"msiexec.exe /fvecms %temp%langpack.msi"

Determining Your .Net Framework Version & Service Pack Level

The following is from the http://support.microsoft.com/ .Net Framework knowledgebase:

Microsoft Support Article 318785

SUMMARY

This article describes how to determine whether service packs are installed for your Microsoft .NET Framework installation. For additional information about .NET Framework service packs, click the following article number to view the article in the Microsoft Knowledge Base: 318836 How to obtain the latest .NET Framework service pack

MORE INFORMATION

Use MMC 1.2 to determine the version of the .NET Framework that is installed

The .NET Framework Configuration tool, a Microsoft Management Console (MMC) snap-in, exposes the full version number, including service packs of the existing installation of the .NET Framework. This tool is only available on operating systems that have MMC 1.2 and later versions.

If your operating system is Microsoft Windows 98, Microsoft Windows Millennium Edition (Windows Me), or Microsoft Windows NT 4.0, you can download MMC 1.2 from the Microsoft Download Center.

The following file is available for download from the Microsoft Download Center:

Download the Immc.exe package now.

For additional information about how to download Microsoft Support files, click the following article number to view the article in the Microsoft Knowledge Base:

119591 How to obtain Microsoft support files from online services

Microsoft scanned this file for viruses. Microsoft used the most current virus-detection software that was available on the date that the file was posted. The file is stored on security-enhanced servers that help to prevent any unauthorized changes to the file.

If MMC 1.2 or a later version is not installed, you can locate the version number of the .NET Framework by viewing the file versions. For more information, see the “Determine the version of the .NET Framework without MMC 1.2” section.

Determine the version of the .NET Framework on a computer that is running Microsoft Windows XP
  1. Click Start, and then click Control Panel.
  2. In Classic view, double-click Administrative Tools.
  3. Double-click either Microsoft .NET Framework Configuration or Microsoft .NET Framework 1.1 Configuration.
  4. In the .NET Framework Configuration window, click About .NET Framework Configuration on the Help menu.

The .NET Framework version number appears in the About .NET Framework Configuration dialog box. If the version number is 1.0.3705.0, you have version 1.0 without any service packs installed.

Note A bug exists in the installation process of the .NET Framework 1.1 SP1. The information in the detail pane and in About .NET Framework Configuration on the Help menu is not updated. It appears as if SP1 was not installed. To verify the installation of SP1, follow the steps in the “Determine the version of the .NET Framework without MMC 1.2” section.

Determine the version of the .NET Framework on a computer that is running Microsoft Windows 2000
  1. Click Start, and then click Run.
  2. In the Open box, type mmc.exe, and then press ENTER.
  3. In the Console1 window, click Console, and then click Add/Remove Snap-in.
  4. In the Add/Remove Snap-in dialog box, click Add.
  5. In the list of available snap-ins, select .NET Framework Configuration or .NET Framework 1.1 Configuration.
  6. Click Add, and then click Close.
  7. In the Add/Remove Snap-in dialog box, select .NET Configuration in the list of added snap-ins. The About button becomes available.
  8. Click About.

The .NET Framework version number appears in the About .NET Framework Configuration dialog box. If the version number is 1.0.3705.0, you have version 1.0 without any service packs installed.

Note A bug exists in the installation process of the .NET Framework 1.1 SP1. The information in the detail pane and in About .NET Framework Configuration on the Help menu is not updated. It appears as if SP1 was not installed. To verify the installation of SP1, follow the steps in the “Determine the version of the .NET Framework without MMC 1.2” section.

Determine the version of the .NET Framework without MMC 1.2

If your operating system does not have MMC 1.2 installed, follow these steps to verify the version of the .NET Framework that is installed. To check the service pack level of the MSI version of the .NET Framework 1.0, start Registry Editor, and then locate the following registry key:

Key Name: HKEY_LOCAL_MACHINESoftwareMicrosoftActive SetupInstalled Components{78705f0d-e8db-4b2d-8193-982bdda15ecd}
Value: Version
Data type: REG_SZ
The OCM version of the .NET Framework is included with Microsoft Tablet PC, Microsoft Media Center, and Microsoft Windows XP Embedded only. For the OCM version of the .NET Framework 1.0, start Registry Editor, and then locate the following registry key:

Key Name: HKEY_LOCAL_MACHINESoftwareMicrosoftActive SetupInstalled Components{FDC11A6F-17D1-48f9-9EA3-9051954BAA24}
Value: Version
Data type: REG_SZ
For both these registry values, the data is in the following format:

1,0,3705,x
The x in this data represents the service pack level.

The .NET Framework version 1.1

With the .NET Framework 1.1, a new registry hive has been created specifically to make it easier to find the service pack level. Start Registry Editor, and then locate the following registry key:

Key Name: HKEY_LOCAL_MACHINESoftwareMicrosoftNET Framework SetupNDPv1.1.4322
Value: SP
Data type: REG_DWORD
The data in the SP value tells you which service pack is installed for the .NET Framework 1.1. For example, if the value of SP is 0, no service pack is installed for the .NET Framework 1.1. If the value is 1, Service Pack 1 for the .NET Framework 1.1 is installed.

Note that this method cannot be used to detect if any hotfixes are installed for the .NET Framework 1.1.