fluggo-media

Frist post

Title *

SummaryWhat I'm doing now, and what I hope I'll be doing.

Description *A few months ago, I thought it would be nice if I had a log of all the things I was encountering when creating Canvas and the media library, and how I was attacking each problem. Aaaaand then months went by. I've installed blogging software before, and then always got busy not writing anything. So this is the first post about fluggo-media, and hopefully I'll be as diligent writing this as I am writing my software. Also: I know I have no readers at this point. I'm hoping someone can come into Redmine later and go back through the News section on this project to study my thoughts on the matter. If they end up being important. I also hope a few strangers stop by and see what I'm working on, and not losing hope that the last commit was a week or two ago. So anyhow: what I'm working on now. h2. Documentation I've got a C# background, so I've experienced awesome inline code documentation at the hands of NDoc (long since eclipsed by Microsoft's own "Sandcastle":http://sandcastle.codeplex.com/). So I thought, "This is the open source community, the same community that produced NDoc. Surely they've got something just as good, since they work with code all of the time." Yeah, no. Linux programmers love text files, and aren't real big on presentation. "Doxygen":http://www.stack.nl/~dimitri/doxygen/ is the prime example of that. Yes, it's inline documentation, but it's poorly structured, and it's ugly as sin. I was adamant that I didn't want to separate my documentation from my code. Working with both together in C# was just so natural, and it made sense: You change the code, you change the documentation to match. Right now, in the git repository, there's a @docs@ target for my SConstruct that attempts to build documentation with "Natural Docs":http://www.naturaldocs.org/. This is a documentation builder that promised to be prettier and more structured than Doxygen _and_ pulled from code comments. The result? Well, difficult to do any sort of serious formatting with it. Not to mention it had some _weird_ formatting choices, not only in its base templates (which use indented paragraphs), but in its HTML generator (which inserts extra spaces after periods-- what? Someone from the typewriter era wrote that.). I experimented for awhile putting my documentation in Redmine. I didn't like separating the two, but with Redmine, I could really control the documentation structure, and I really liked Textile. I didn't get much of anywhere, especially since I knew it would fall behind the code. Every time I had searched for documentation generators, though, I kept tripping over "Sphinx":http://sphinx.pocoo.org/, the documentation generator for Python. Now, Python has some nice documentation—and they have a lot of it—but I kept skipping over it because I could only do Python docs inline. My C code would have to have separate documentation written. I finally resolved to give it a try, though, because it seemed to have broader language support and formatting choices than Natural Docs, and _did_ have the benefit that my documentation could be versioned right alongside the code. And you know what? It's beautiful. I love it. The results it produces are pretty, right up there with the Python docs themselves. I don't have to mess with any of the default templates. I also learned that it's perfectly OK, _especially_ in the case of C, to have documentation separate from the code. The reason is that you _really_ don't want the interfaces to change on you. Sure, you might add a function or two, and you might forget to document them, but you shouldn't be going back and changing old functions. So that's one thing I'm working on now, getting a whole bunch of documentation written in reST for Sphinx. h2. Windows The other big thing I've gotten sidetracked with is a Windows port. All of the code written so far has been written with GNU/Linux in mind. I had thought that I might start a Windows port waaay down the road. I changed my mind the other day; Chris, my brother, is interested in contributing to the project, and he's on Windows. I thought, well hey, he should be able to contribute to the Python side of things, and I've been careful to pick cross-platform tools. How hard could it be to get a Windows build going? Oi! I've programmed on Windows for years. You might say I'm a native there. But all I really ever worked with was Visual Studio (and Borland C++, and QuickC—you remember QuickC?). Getting a build working without Microsoft's help—that is, with MingW and company—is not easy! I might have had an easier time if I'd chosen to do it with Cygwin. I've worked with Cygwin and I'm used to it. Part of the reason I didn't was that SCons wasn't available for Cygwin. Another was the warning given at a lot of sites that building with Cygwin always left the possibility that you accidentally dragged a Cygwin dependency into your binaries. No, sir, that wasn't for me. Even if MingW is harder, I'm sure I can sort it out and be more confident about the build than I would be with Cygwin. I still think that's true, but MingW and MSYS aren't always the easiest to work with. I'll save the details of my arcane incantations for later, but suffice it to say, in terms of ease of use for the programmer, UNIX has got Windows' butt thoroughly kicked. h2. Also: Canvas The Windows thing is kind of a sidetrack. The last thing I was working on in the actual code was support for some of the major features of the Canvas UI, such as narratives, timelines, anchors, groups, etc. Some of that scares me, so it's good to get a break before I go back to it. The good news, and the reason I can move on to that stuff, is that most of the base class library is finished. There are simple tools for the basic tasks: demuxing a file, decoding a picture/sound, reconstructing a picture, editing it, mixing it, restructuring it, encoding it, muxing it, saving it, and displaying it. They all need to be expanded later, but they'll do to get the project off the ground. So there you have it. Both a first post and a progress report. I hope to commit, sometime soon, a workable Windows build process, and maybe soon after that some of the Sphinx docs, since those will be most useful to anyone hacking on the project. Maybe I'll attract one or two someones like that. Later.

Preview | Cancel

What I'm doing now, and what I hope I'll be doing.
Added by Brian Crowell 608 days ago

A few months ago, I thought it would be nice if I had a log of all the things I was encountering when creating Canvas and the media library, and how I was attacking each problem. Aaaaand then months went by. I've installed blogging software before, and then always got busy not writing anything. So this is the first post about fluggo-media, and hopefully I'll be as diligent writing this as I am writing my software.

Also: I know I have no readers at this point. I'm hoping someone can come into Redmine later and go back through the News section on this project to study my thoughts on the matter. If they end up being important. I also hope a few strangers stop by and see what I'm working on, and not losing hope that the last commit was a week or two ago.

So anyhow: what I'm working on now.

Documentation¶

I've got a C# background, so I've experienced awesome inline code documentation at the hands of NDoc (long since eclipsed by Microsoft's own Sandcastle). So I thought, "This is the open source community, the same community that produced NDoc. Surely they've got something just as good, since they work with code all of the time."

Yeah, no. Linux programmers love text files, and aren't real big on presentation. Doxygen is the prime example of that. Yes, it's inline documentation, but it's poorly structured, and it's ugly as sin.

I was adamant that I didn't want to separate my documentation from my code. Working with both together in C# was just so natural, and it made sense: You change the code, you change the documentation to match. Right now, in the git repository, there's a docs target for my SConstruct that attempts to build documentation with Natural Docs. This is a documentation builder that promised to be prettier and more structured than Doxygen and pulled from code comments. The result? Well, difficult to do any sort of serious formatting with it. Not to mention it had some weird formatting choices, not only in its base templates (which use indented paragraphs), but in its HTML generator (which inserts extra spaces after periods-- what? Someone from the typewriter era wrote that.).

I experimented for awhile putting my documentation in Redmine. I didn't like separating the two, but with Redmine, I could really control the documentation structure, and I really liked Textile. I didn't get much of anywhere, especially since I knew it would fall behind the code.

Every time I had searched for documentation generators, though, I kept tripping over Sphinx, the documentation generator for Python. Now, Python has some nice documentation—and they have a lot of it—but I kept skipping over it because I could only do Python docs inline. My C code would have to have separate documentation written.

I finally resolved to give it a try, though, because it seemed to have broader language support and formatting choices than Natural Docs, and did have the benefit that my documentation could be versioned right alongside the code. And you know what? It's beautiful. I love it. The results it produces are pretty, right up there with the Python docs themselves. I don't have to mess with any of the default templates.

I also learned that it's perfectly OK, especially in the case of C, to have documentation separate from the code. The reason is that you really don't want the interfaces to change on you. Sure, you might add a function or two, and you might forget to document them, but you shouldn't be going back and changing old functions.

So that's one thing I'm working on now, getting a whole bunch of documentation written in reST for Sphinx.

Windows¶

The other big thing I've gotten sidetracked with is a Windows port. All of the code written so far has been written with GNU/Linux in mind. I had thought that I might start a Windows port waaay down the road. I changed my mind the other day; Chris, my brother, is interested in contributing to the project, and he's on Windows. I thought, well hey, he should be able to contribute to the Python side of things, and I've been careful to pick cross-platform tools. How hard could it be to get a Windows build going?

Oi! I've programmed on Windows for years. You might say I'm a native there. But all I really ever worked with was Visual Studio (and Borland C++, and QuickC—you remember QuickC?). Getting a build working without Microsoft's help—that is, with MingW and company—is not easy!

I might have had an easier time if I'd chosen to do it with Cygwin. I've worked with Cygwin and I'm used to it. Part of the reason I didn't was that SCons wasn't available for Cygwin. Another was the warning given at a lot of sites that building with Cygwin always left the possibility that you accidentally dragged a Cygwin dependency into your binaries. No, sir, that wasn't for me. Even if MingW is harder, I'm sure I can sort it out and be more confident about the build than I would be with Cygwin.

I still think that's true, but MingW and MSYS aren't always the easiest to work with. I'll save the details of my arcane incantations for later, but suffice it to say, in terms of ease of use for the programmer, UNIX has got Windows' butt thoroughly kicked.

Also: Canvas¶

The Windows thing is kind of a sidetrack. The last thing I was working on in the actual code was support for some of the major features of the Canvas UI, such as narratives, timelines, anchors, groups, etc. Some of that scares me, so it's good to get a break before I go back to it. The good news, and the reason I can move on to that stuff, is that most of the base class library is finished. There are simple tools for the basic tasks: demuxing a file, decoding a picture/sound, reconstructing a picture, editing it, mixing it, restructuring it, encoding it, muxing it, saving it, and displaying it. They all need to be expanded later, but they'll do to get the project off the ground.

So there you have it. Both a first post and a progress report. I hope to commit, sometime soon, a workable Windows build process, and maybe soon after that some of the Sphinx docs, since those will be most useful to anyone hacking on the project. Maybe I'll attract one or two someones like that. Later.

Frist post

Documentation¶

Windows¶

Also: Canvas¶

Comments