Comment

Comment - Know Your Thoughts

Purpose

Comment was starting as a ruby app for KDE (named “Komment” back then), but is now being ported to C++ using Qt4. It allows the user to comment books or magazine-articles with which they have to work.
For example if you are writing a elaboration over a specific subject you gonna read lots and lots of books but you can’t remember exactly everything you read in one of them or your thoughts while reading them. So, with Comment you can simply write your thoughts down. Ok, ok, for that a normal Office-Application would do it also, but the great advantage of Comment over those is, that it is designed with the focus on this purpose, to make that easier: You don’t have to bother over the style and if you are in the right position of the list.
You simply write a comment, linking it to a chapter, paragraph or what else of the book and tagging it. You’ve done that you can browse through all what you have ever written to that section of the book or through all of your comments tagged with the same subject.

File-locations

Comment works in a way that most (all, except for translation) file can be stored in one of two (on Mac three) locations, each for another purpose.

BundleData-location (Mac only)

The Resource-directory inside the .app-Bundle. There everything is stored Comment should have when it’s distributed. The common definitions, the default-templates, the translations.

SystemData-location

In the SystemData-location everything is stored that is used for all users on this system. On Linux and Windows the files stored in the .app-bundle on Mac are stored in this location. But even on Mac you can store additional data here.

Mac: /Library/Application Support/Comment/
Linux: /usr/share/Comment/
Windows: %ProgramFiles%/Comment

UserData-location

Here the user him/herself can add his/her own data. In first place this will be the publications and libraries, but it is also possible to store definitions or templates here. So the user may expand Comment without the need of root / administrator-rights.

Mac: ~/Documents/Comment/
Linux: ~/Documents/Comment
Windows: %APPDATA%/Comment

Translated directories

The names of the directories in the UserData-location are translated. Be aware of this! So, while Comment searches for “definitions” in an english environment it searches for “Definitionen” in a german environment.

loading the data

The content of the files is loaded in the order I described the locations. So a template stored in the UserData-location overwrite the template in the SystemData-location, which itself overwrite templates in the BundleData-location (on Mac). This way the user can have the experience he / she wants or needs.

Preference-files

The preferences are stored for a user, there are no system-wide preferences, but maybe they will come at some point of development, if demanded.

Mac: ~/Library/Preferences/
Linux: ~/.Comment/
Windows: %APPDATA%/Comment/

Extensibility

You can easily add a new template for presentation of the content or even add new types or publications by simply creating files that have a specific layout and store them into the right folder on your disc. Viola, you gave Comment a feature I’ve never thought of. Of course you can share those files also with other users, for all they have to do is to save those files on the disc in the corresponding directory. It’s that easy.

Templates

The template-files are normal html-files that contain some “macros” to let Comment know where to write the content into. You can write your html-file they way you want with the app you want and if you like what you see you just rename it so it ends with .template and then save it into the template-directory into the userdata-location of Comment (see above)

Definitions

A definition-file is a xml-file that list all the fields of the meta-informations a publication have, like author, date, … For each field you have to write of which type it is (string, int, double, person, …) and whether it shall be shown in the list of the startup-GUI so you can order the list according to that field. Afterwards you just store the xml-file (with .definition as suffix) into either of the data-locations of Comment and viola, the next time you start Comment the startup-GUI has a new entry in the list: Your own-written publication-type.

Getting the development-version run

Since I don’t have an installer yet you would need to copy some files into the right folders by hand in order to get Comment running. All files are in the zip-file, the subfolder “files”.

First steps 

Creating a Book/Magazine (~ publication)

After you’ve installed Comment you can add a new book or magazine-article to the library of Comment. For this you can write down all the bibligraphical informations you have or need. Those informations (beside the title) are only for yourself to be able to find quickly the “Book” in Comment on which you want to work, even if you have several volumes or different serieses of one book. And in the same window in another tab you can write down the structure of the book (chapters, subchapters, paragraphs, …). Since the comments you gonna write are bound to a ’section’ you should copy the structure of the book so it’s gonna be easier for yourself to find the appriopriate pages in the book. If you think the structure of the book is too loose you can even add sections of your own into it (they gonna be marked so you can’t mistake them for a books-own section).
At last you may add a tag-hierarchy to your book/magazine. If you already know what kinds of themes there will appear you can already add the tags for them and bring some structure into them.
All of the informations you can edit at each time.

Add a new comment (~entry)

If you want to add a comment you choose the toolbar-button “Add Entry” or go via the menu (”Edit” - “Add Entry”) to do that. Now you get a new windows in which you can write the content of your comment but also give some informations about it.
For one thing you have to bind the entry to a specific section of the publication. And you can bind it to one or more tags. If you see while writing that you need a new tag you haven’t created for the publication yet you just add that tag to the taglist of the entry, the new tag will automaticly created for the whole publication.
Beside those three informations you can add optionally some more to the entry:
A brief description for the entry
A hint where to find the text the entry relates to (the line for that is named ‘concerning’)
The date of creation will be added automaticly to the entry.

Editing a publication or entry

Just use the appropriate buttons and you get the very windows you used for creating.

Viewing the publication

After you created a publication and already added some entries you can quite easily browse through them. There are two major ways working quite the same:

  • browse by section
  • browse by tag

On the left side of the main-window you see two tabs, each containing one hierarchical list. The first is for the sections of the book, the second for your tags. If you choose either a tag or a section the main list (the top space on the right side of the main windows) will show all entries for that section / tag.
Naturally you can search for a string in the content of each of your comments also, the result will be shown in the same place.
You choose one of them by clicking on the listitem. Then the entry appears in the quick-view below the list. If you want to edit any of it (the tags, the section it belongs to, description, content) you just click on the content under or the description above the meta-information or the buttons of the tool- / menubar.

If you want to see the bibliographical informations of the publication you work actually on (e.g. if you forgot which volume it was you opened) you can either open the “Publication” window in the “Edit”-Menu or you choose the “Publication-info” of the “View”-Menu. Then you get a html-styled list of all the informations of the publication with the section-hierarchy on the bottom. This can be easily copy&past-ed but not edited. Since it is just a view, not an edit-ui.

SVN

You can get the latest version of the sourcecode from the SVN of sourceforge. That would be the proper command:

svn co https://comment.svn.sourceforge.net/svnroot/comment/trunk comment

Roadmap

What do I want to achieve when?

  • Build 4:
    Working on the Startup-GUI so there is something visible
  • Build 5:
    Creating the first draft for the main window
  • …
    Doing a lot of work developing the GUI and working on the backend things
  • Beta1:
    Getting all working in C++ what worked in ruby

The BuildX-releases will be small stepstone-release beetwen the Beta-Release. They gonna be numbered unbroken, even after Comment 2 will be released. So if build517 is the last build before Comment2 build518 will be version 2.0 and build519 the first after Comment 2. The Build-Releases are for new functions, not for ‘only’ bug-fixing. But since I’m not at Comment 2 I have time to consider how to call bugfixings. Maybe just “Comment 2.0.1″ will be fixed-version of Comment 2.0 and Comment 2.1 will be released after some BuildX-releases when new functions are ready for usage. So you have a different line between bug-fixing and development.

This roadmap is just a preliminary one. It could change completly during the development.

News

All news concerning Comment will be published on my blog as posts. So you’ll find everything in one url. If you don’t want to bother will all the other stuff I post here you can simply browse the Comment-Category and see just the posts that deal with Comment.