draft0 - a shared blog by just some people

I've decided to not publish version 1.0.0 of SBWG.

Very early on I devided against a versioning approach that allowed me to stay below version 1.0 for a very long time by only incrementing the version number by 0.0.1 for important changes but rather chose to increment the version and publish a new version whenever. I stick to this approach because it allowes me to express felt overall progress in the version number. But now that the goals that I at some point set for version 1.0.0 are nearly reached (they pretty much are), this leaves me in a spot where publishing version 1.0.0 would be the next thing to do despite the fact that it's not actually really absolutely perfect, yet. Absolute perfection isn't really my approach. It's still more like a learning project.

So to avoid having published a version that looks perfect on the label but isn't inside, I will skip this version number. Don't get me wrong. My goals are. I've tested it more than I thought I would and thought of potential problems and fixed bugs that I'd argue are not something you'd expect most shell scripters to catch. It definitely works reliably for what it is intended and at least works well for much more than I thought it would in the first few months of starting this project.

So, there is no link in this entry. No new version published today. The next version will be 1.x.x something.

Alright. Now that that's done, I can start to implement new features again next year.

I made it my goal to harden SBWG before I start to implement new features. Before I call the next version of this project 1.0 I want to make sure that unexpected input from the command line or from source files, absurd numbers of absurdly long tags and content items, stupidly weird filenames or random binary data as tag values as well as purposfully created traps in the various places where input is processed are handled well, meaning that nothing fails unless there is no sensible way around it, and if something fails, that nothing breaks. Data should be filtered carefully, errors should be handled well and whereever possible data should be made processible if it was supplied in an unprocessible form to reduce the chances of errors. On top of that I wanted to make sure that the script did its job in a reasonable amount of time considering the circumstances. I mean, it will never be very fast. Bash is just not the right language for that. But there certainly were some repetitive tasks that could be improved. Fot the latter I created a simple caching functionality that will probably be extended in the future. I managed to reduce the (calculated/estimated) generation time of my biggest test web site from almost 300 years to a few days. Actual web sites will of course not take that long to generate, even on a slow machine. A huge web site will maybe take up to one day to generate completely, even without the new options that keep the script from re-generating existing unchanged parts of the web site. But before sombody will try to create such a big web site with SBWG I will probably have improved speed further. And even then it's a worst-case time.

As part of the aforementioned goals I have started working on last new feature before version 1.0. I call it the pathreducer. Since many of the files created by SBWG are named after the tags they represent, they can become quite long and contain almost any printible character, including multi-byte unicode characters or characters of character sets I haven't even heard of. I definitely don't want to restrict more than I already have what characters and how many of them tag values can contain. Especially filesystems used by operating systems from Microsoft are relatively restrictive in maximum allowed directory, path and filename length and allowed characters. By default the pathreducer is not used. But if enabled via command line option or in a web site's settings file, it will filter directory and filenames and shorten them to a user-defined maximum length. If the pathreducer decides to change a path elements it also adds a 6-character hash value to make shortened or otherwise reduced path elements as good as unique.

That works well for now and even can create 8.3 or 6.3 filenames for old DOS filesystems. But the result is not very nice because it isn't aware of what filesystem it is going to write a file to. To be save it removes more characters than it would have to for ext and NTFS filesystems. In the future I may extend the pathreducer to detect the filesystem at least of the root of the output directory automatically and decide how exactly path elements should be reduced according to the actual limitations of the present filesystem. Than it may even be enabled by default, even though it can increase the generation time quite a bit.

There are still some tests that I want to do and I will probably find some more things that I want to fix before version 1.0. But I see light.

As foreseen I've made slow progress in development of SBWG, the script that generates this web site, because I want to test and improve it with the current feature set before I start to implement new features. The former is necessary. The latter is more fun. But today I've reached a point where I can say that the only thing left to do before I call it v1.0.0 is testing edge cases and things that I didn't think of testing before, as well as fixing potential bugs discovered from this testing.

So, version 0.9.6 is out, everything is working, The README file, other documentation included in the package, the example website, the included style sets and partly even the code quality has been deemed satisfactory, and I hope I'll find the time to test all sorts of weird stuff and discover and fix some bugs next month, at which point version 1.0.0 will be published and I'll finally be able to allow myself to start working on new features, some of which are awaited by both regular users of the script.

So, I'm still making slow process with SBWG. I had more fun with it when I was out and implementing new features. But I find it important to finish version 1.0.0 with the currently defined set of festures and goals, which include finishing documentation, testing and code hardening, which are less fun for me.

I've always treated the third level of the version number (x.x.thisone) as a means to declare a new version done when I feel like having achived something. So today I declare version 0.8.10 as done. There really isn't much left to do to meet my milestones for v0.9.0. And from there on it will only be testing and possibly a little bit of code improvements to get to my set goals for v1.0.0.

I'm looking forward to this not only because I'll like the feeling of having achived a goal, but also it will mean that I'll be free again to introduce new features. I still have more ideas than necessary about what to do with SBWG.

But right now I'm enjoing the fact that I'm able to make myself believe that it's okay to move on as slowly as I want and let my colloquial executive dysfunction do its think without impacting my feeling of self-worth oo much.

Lately I'm making only slow progress with SBWG. I'm determined to make this something that I'm comfortable with sharing as 1.0.0 online. Something that works and could arguably be called a somewhat finished peace of software. That doesn't mean that the todo list won't be huge at the point I change the version number to 1.0.0. But it should be in a relatively good state for what I've decided it will encompass at version 1.0.0. "Relatively" because it's still also a learning project and I would write many things differently if I started over, which means I'll have to rewrite them at some point to be satisfied with SBWG.

So, the goal and roadmap is set for v0.9.0 and v1.0.0 and a large part of what is still to be done is documentation and other things I don't enjoy doing as much as starting to implement new features. I'm holding back on working on things that are not on that roadmap so that I don't introduce new bugs and the need of further testing. First I want to improve what SBWG can already do.

That means that there won't be many interesting changes in the coming weeks (or maybe even months). Today I've decided to call what I've currently got version 0.8.9 and publish it on the project page.

I rarely wrote updates on SBWG before now. I just worked on it whenever I had time and felt like it. And that was quite often. But this is my website where I want to feel fine with pretending that what I'm posting is of any real interest to anybody. So I may post more updates on what I did to approach my goals for SBWG 1.0 from now on. It is rare for me that I invest so much time in a single project. And since I'm starting this blog at the same time and want to fill it with a lot of content, it is time to combine the two.

Some things that I did and changed but didn't report on so far: The header format of entry and page source files has been changed completely (simplified), the generated HTML became more complete, the idea of a sourced settings file came (first to me, then reality), new tag types have been formed, the sorting of blog entries is much more mature now, many more customisation possibilities cropped up and I developed an overall vision of what SBWG will become.

The code grew so much over the time. But it was mostly for very good reasons. I'm feeling overall quite content with how clean the code became and how many contingencies I took into account. It's probably still not "professional" code. But it is a new level of professionalism for me and my Bash scripts. Should I ever come close to getting through all the tiny, small, irrelevant, important, stupid, huge, new and old to-dos, it would probably be quite presentable. So many small features have been added that I hadn't thought of when I startet to write SBWG. Multi-author blogs are supported now, tags can be substituted for icons, a basic RSS feed works, ...

The way tagpages of topic (top:) tags are displayed is pretty much complete and the way I intended it to look when I first thought of splitting blog entry tags into two tag types. Basically, categories (cat: tags) are like classic tags in blogs: a way to add keywords to entries and list all entries that are tagged with that keyword. Topic tags on the other hand are meant to tag entries that talk about a certain topic about which a visitor might want to read up regardless of when individual entries on the topic have been posted. A topic tapage represents an index on a topic. It lists all the entries that are relevant to the topic in a structured way. You could write a book, one chapter per blog entry and have it simultaniously presented as a weblog (with category tags) and as a orderly indexed book in which visitors up a certain chapter. I still have to make up my mind on how I want to structure my own blog entries. But the fuctionality in the software is there. I will very likely also add another feature that enables structuring entries and pages into custom menues. So the options for web site builders will be grand with this weird took.

By now the initial introduction of SBWG that I've written in the first entry in this category is not only incomplete but in its details largely obsolete. SBWG matured a great deal in the last months and I feel like publishing a new version. I have started documenting stuff properly in the README and other files included in the package since I have a set goal for version 1.0. I will likely add no new features until I have made something that I can satidfyingly call version 1.0. Right now I'm in between versions 0.8.6 and 0.8.7. I call in-between version wip (work in progress). I feel like publishing what I have so far right now. So here is a wip version: 0.8.6-wip.