Tuesday, April 29, 2008

Visual Book Designer

I've been writing and maintaining a set of javascript tools or "gadgets" to help facilitate the creation and organization of books. By adding in some AJAX functionality, these scripts are able to automate, or semi-automate some common tasks for new editors. One of my older tools that I called the "Book Designer Gadget" was useful for outlining and designing a new book. You would type in a list of pages, one per line, and the gadget would create all the necessary wikitext for the table of contents page in your book. It would also do things like help assist you in creating basic navigation templates for your book, and properly categorizing your new book.

I decided to give the Book Designer Gadget a major overhaul, and I've created a new "Visual Book Designer" tool that should be even easier to use and more powerful. I would like to talk about that tool a little bit here, because I feel like it's a great prototype for the kinds of tools that Wikibooks is going to need in the future to help attract a new generation of technically un-savvy authors. This new gadget is completely visual, and it doesn't require any technical expertise to use.

To install and use the gadget, there are three easy steps:
  1. Create an account on en.wikibooks
  2. Go to [[Special:Preferences]], and on the gadgets tab check the box "Whiteknight's Book Creator". This will install all my tools, including the Visual Book Designer automatically. No need to edit your monobook.js file at all, the gadgets extension does all the work for you.
  3. Go to the form at [[User:Whiteknight/Visual Book Designer]] to see and interact with the gadget.
So what does the gadget do? When you load the page, you should see the following screen. Notice that there are some slight differences in IE, which are still being ironed out.

Everything you see here can be clicked on, and many options can be changed. If we click on the title "New Book", we can change it:

The rename function performs a quick AJAX page request to determine whether the page exists or not. You are not allowed to create a new book with the same title as an existing book.

The small links below the book title, "Headings" and "Subpages" are the most important. These are the buttons that allow you to construct your outline. Clicking either "Headings" or "Subpages" will open a box where you can list the names of page headings or subpages, respectively. I'll demonstrate with subpages since they are the most important. Click the "Subpages" button, and enter a list of pages that should be added to your table of contents, one per line. Click save when you are done adding subpages to your outline:

You will notice that on each subpage, we have the option to add sub-subpages, and more headings. In this way, you can easily create books using a variety of hierarchies, like "Book/Page", "Book/Chapter/Page", "Book/Chapter/Subchapter/Page", etc. Astute observers will notice little links for "Wikitext" under each page in our outline. Clicking on the "Wikitext" link will automatically generate the necessary wikitext to create that page:
Notice that it adds all the necessary templates for organization, it adds necessary categories, and it creates links to all your subpages. From here, you can copy+paste the text to your page. Very astute observers will also have noticed a small link that says "Edit" under the subpages as well. On wiki, when I show you a button or a link that says "Edit", what comes to mind? Clicking on that link will open an embedded edit window, right here in the middle of the gadget, where you can edit the page in question automatically:

When you open the edit window, all the text and a handy summary are filled in for you. You can save or preview your edit just like you can in a normal edit window (because it is a normal edit window). You can do this for each page in your book too, not just the main page.

There are many more options that I won't discuss in detail here, but I hope that you get an idea of how useful a tool this is for new book authors. You can layout and design a book, following Wikibooks community best practices, without having to write a single character of wikitext. Here is a quick list of additional features:
  1. You can save a partially completed outline to a page on the wiki, and load it into the gadget again later.
  2. You can add your book to one or more subject categories by selecting from a convenient list. You don't need to know the exact name of the category, or the location of the bookshelf, or anything to make this work.
  3. You can create the necessary navigation templates, but picking from one of a small set of predefined alternatives. Once the template is created, you can modify it to your heart's content.
  4. You can add text to each page and each heading by clicking where it says "[Click here to edit page text]". The editor isn't as large as the regular page editor, and it doesnt have any of the normal editing buttons, but you can write a short blurb to get yourself started.
  5. You can add comments to the outline by clicking where it says "[Click here to edit comments]". Comments are visible to you on the outline, for making reminders and short notes, but are not visible in the book when you create it.
This should serve as a good, but brief, introduction to the new gadget. People who may be interested in writing a new book, but have been worried about the learning curve of learning how should definitely check it out. I'm also looking for people who would be willing to test it out, help me identify any bugs or shortcomings, and make feature suggestions.

Thursday, April 24, 2008

Adopt A Book - April 2008

As always, Wikibooks tends to have a high-author turnaround rate. This means that people tend not to finish what they start, and many books are abandoned before they are finished. The problem with this, of course, is that books in poor condition take a daunting amount of work to get fixed up, and do not readily inspire new contributors to help out. Here then is a short list of some books that I've found today that could really use a helping hand:
  1. [[Data Structures]] This book isn't in poor condition, in fact I would say that it's in a particularly good condition. However, it isn't featured yet and it isn't under active development. This book really does have the capability to move up to that next level if a few of the details could be worked out. Chapters here tend to be large, and a reorganziation effort might be required here as well. If you know a little bit about computer science and data structures, and are willing to do some work on organization, it would be much appreciated.
  2. [[Java Programming]] This book is pretty big, and also in decent condition. However, problems with formatting and page naming are really keeping this book down. This book needs some organizational and aesthetic work, and a few of the later chapters are empty or stubbish. This is another book that, with some TLC, could become a featured book on Wikibooks.
  3. [[Programming:PHP]] This is a prime example of the old-style naming convention that these old programming books used to use. The Programming: pseudonamespace has been deprecated, and this book should be renamed to "PHP Programming", or something similar. The formatting in this book, at least on most of the pages I saw, is pretty fantastic, although there hasn't been any major contributions in a few months. A few of the later chapters need to be improved, however.
  4. [[Wiki Science]] You almost wouldn't believe it, but in Wikibooks some of our books about wikis are in pretty poor condition. This one is off to a good start, and there is some material here that a new contributor can really grab on to. If you know a thing or two about wikis, and want to share your knowledge with the world, this book could use your help.
  5. [[MediaWiki Administrator's Handbook]] Are you an admin, bureaucrat, checkuser or steward? Do you have a little experience with some special user rights on a MediaWiki project? There are a lot of tools that aren't really open for the public to view, and a lot of the admin tools aren't always well documented. This book is a good start in this, but it's obviously outdated and incomplete.
Sorry to favor the computer books so much this time, but I've been going through the list of them recently looking for naming convention stragglers. The computer and programming books have a history of being improperly named and organized, and even today some of these old problems persist in these books. People who know these subjects and are willing to do some authoring or organizing work are definitely encouraged to come help out with these.

Wednesday, April 9, 2008

Wikijunior Big Cats

[[Wikijunior Big Cats]] is finally receiving some of the attention that it deserves. It's an excellent book aimed at young children, and has a lot of great images of cool cats. Textbook-l received a note today about how this book has been published on Scribd.com, and about how the book was in preparation to be published and distributed. I'm not closely involved in this project, so I don't know much about it. I do know that this has been in the works for a long time, and has been the subject of several heated discussions between Wikibookians and WMF "outsiders" in the past. Many Wikibookians who were involved in this project have since left Wikibooks, so it's amazing to me that work has continued on it silently but diligently all this time.

Anyway, this is just a short update note. Like I said, I don't know all the details about this, but I'll post information when I learn it.

Monday, April 7, 2008

"Reasonable Basic Algebra" Book, LaTeX help needed

Textbook-l received a very nice email yesterday from a Mr. Alain Schremmer, who operates the website FreeMathTexts.org. Mr. Schemmer (and I apologize right now if he should be referred to by a different salutation) has graciously given permission--but more importantly also a suggestion--that the books that he's been developing should serve as the basis for books on Wikibooks.

His books are already released under the GFDL, so technically no permission would be required anyway. I do think it's more friendly and polite to get permission anyway, as getting into contact with authors before we "steal their stuff" tends to build some much-needed friendships for our little project. More importantly, he alerted us to the existence of these books and suggested that they would make excellent additions to the Mathematics bookshelf at Wikibooks. I agree with him. As anybody who has read my blog before should know our mathematics book, and especially our Algebra-related books, are in need of help. We recently received a donation of a Linear Algebra book, and that project is going slowly but progress is being made nonetheless.

The problem with these books, the first of which is called "Reasonable Basic Algebra", is the same as the problem we are having with the Linear Algebra book: These books are written in LaTeX, and conversion to wikitext is proving to be very difficult to do. There are some specific problems that I've been finding, and I'll try to list some of them here:

  1. There are no automatic conversion tools, at least not ones that are robust, that can do the conversion automatically. Even the best tools require a lot of human intervention for even moderately-complex LaTeX. The books that I've been seeing are definitely "extremely complex".
  2. LaTeX mathematics have far more options then the MediaWiki mathematics rendering engine. Even if we properly insert the tags where they need to go, many equations are going to produce errors because of unknown directives
  3. #2 assumes that we put the tags in the right places. this is not easy, and often requires human intervention.
  4. LaTeX has far more formatting commands and options then MediaWiki does. We could, of course, try to create a million templates to handle all of these, but that isn't particularly practical from my point of view. Plus, pages with hundreds or thousands of template inclusions is going to put a huge strain on the servers.
I was interested at one point in trying my hand at creating a scalable recursive descent parser for LaTeX that could help with the conversion process. Unfortunately, I haven't had the time to do it myself and I don't expect to have that much time available in the foreseeable future.

I want to put out an open call to software developers or volunteer coders who might be interested in helping to create a LaTeX -> MediaWiki book converter. Since there is a little bit of time left in the application cycle, this might make a good Google Summer of Code project. If anybody is interested in this, I would love to hear from you.