## Comment viewing options

### Well...

I wasn't convinced this qualifies as general language theory, more like Haskell-user-specific literature. I shall post future issues to the home page.

--Shae Erisson - ScannedInAvian.com

### Well...

Do that if/when you think they warrant the attention. The first issue is, of course, of more general interest, simply beacuase it's the first one...

### Language-specific is great

Language-specific is my favourite sort of content on LtU and there's currently a shortage, so good on you for posting! Everyone should post all the most interesting things about their favourite languages -- since we're all into different ones the result is a lot of variety and new ideas. After all it's the design and study of actual languages that makes theory useful.

"The programming languages weblog" is not just meta but plural too! :-)

P.S., homepage vs. discussion area makes no difference to me anymore since I read LtU via /tracker.

I like Andrew Bromage's article and I agree that the programming/writing analogy is a useful one.

I still use pbook to whip important modules into shape and make them understandable. My good examples are mixed up in code at work but I have one Lisp example on the web (text and pdf). Unfortunately pbook itself is a very bad example: being its own first application I got carried away and ridiculously over-commented it.

The cool thing is that when you read a program on paper lots of obvious problems and solutions jump right out at you. So we have a very simple and brainless algorithm for improving programs: print them out and just do what obviously needs to be done!

### SLIME

I remember now that I quietly pbook'ified the major source files in SLIME perhaps 9 months ago. This program is written for real use (rather than for publication) and about 60 people have hacked the code in total over the past 18 months. I doubt that many recognised the pbook formatting.

Out of curiosity I generated a PDF from the current version of one of the major source files. I haven't reread it now (79 pages) but the overall structure looks reasonably clear and linearly-readable.

I would really like this to be a program that a sufficiently motivated person could printout and read and thoroughly understand in one (perhaps fairly painful) day. I'm not sure if that is a high or low maintainability target or whether we're anywhere close to it. (Probably a long way away, actually, since the full program seems to be about 500 pages.)

I wonder what some particularly easy-to-read program are these days, from the ones that people really use?

### Issue Two

--Shae Erisson - ScannedInAvian.com

### Issue Three

Issue Three is online, this issue has an introductory theme.

--Shae Erisson - ScannedInAvian.com

### Other formats available?

Just curious: why was the first issue published as PDF and the follow-ups only as Wiki pages?

Things like this are interesting for off-line reading (in the train), so I would welcome PDF versions of the articles. Of course, I the Wiki pages make it really accessible for a quick read and new audience, so I'm not suggesting to replace these with PDFs.

### Content quality over presentation quality.

In the beginning, I wanted to do it all with wikipublishing.

But, quite a few people (fifteen or twenty) told me they would strongly prefer pdf/ps format because the presentation is more attractive. So the first issue I went with pdf/ps output with LaTeX or plain text input.

I assume that real for-pay journals check each article for:

• grammar
• spelling
• technical correctness
• related works
• formatting

The first issue had negative feedback in terms of spelling, grammar, etc.

The problems I discovered were that first, I'm not familiar with LaTeX, and second, I don't have enough free time or enough skill to do a high quality check for each item above for every article.

My goal for The Monad.Reader has always been to present the information available in research papers in such a way that it is accessible to a motivated commercial programmer like myself. I'm self-employed, I organize The Monad.Reader for fun on my spare time.

I chose to distribute the workload (and the motivation) by switching back to my original idea of a wikizine. That way, all the authors, current and previous, have the opportunity to check the items in the list above.

If you want pdf or ps output, there's an easy way to get it. Write a tool that converts MoinMoin syntax into LaTeX. It's easy to see the source of a page by appending ?action=raw to the url. For example, here's the source of the FpVsOo article. If someone writes such a tool, I will use it for all issues, past and future. Pdf/ps output is still the number one request I get.

I will also take this opportunity to request more articles and authors, please send me summaries of Haskell related articles you want to write!

--Shae Erisson - ScannedInAvian.com

### Something about sizzle and steak...

To be fair, it seems like you got just the one bit of negative feedback on the grammar and spelling as opposed to the many requests for ps/pdf formats.

I appreciate that it may be easier to set up the Reader as a wiki site, but honestly, it may end up costing you an audience in the long run. I know I skipped the second issue completely because it wasn't available as a pdf, I've not read the Haskell For C Programmers tutorial for the same reason, and sadly I'll likely not bother with issue three of the Reader because of this as well (though a few of the articles seem interesting enough that I might print the web pages and plod through those). It may seem like a silly reason to skip some potentially valuable information, but I (like most people) have too much on my plate already, and if the appearance and convenience levels of a document are too low, then I'll gladly move on to something more pleasing.

As for converting MoinMoin to LaTeX, do you know of any comprehensive, centrally located reference on the syntax? The information available at the MoinMoin wiki is poorly presented and spread across 10 or so documents (yet another downside to the "online publishing revolution" -- hundreds of years spent on figuring out what makes text pleasing to read and we're willing to throw it all away for a bit of ease of publishing and distribution), and google is turning up a lot of false positives.

-30-

### [OT] Why PDF?

Maybe you could flesh out the reasons for prefering PDF? Is it mostly more convenient because you can print it out with fewer steps (since you don't have to click print on each of the five different articles)? Can you give more specific feedback on what you don't like about the apperance? Here's my stab at creating a pdf for Issue #3. That was created by a combination of print to postscript in Mozilla for each article, psjoin to concatenate the files, and a final ps2pdf.

### It's not the file format per se

It's more that HTML is not good for (printed) typesetting, especially when no special care is taken (like using a print stylesheet with different fonts, font sizes, etcetera).

So just converting the thing to PS and then to PDF won't help much. Compare a LaTeX typesetted text with an HTML document on paper, the former is much more pleasent to read. Reading from screen is a different manner, but especially a lot of Wikis could be improved (most importantly: get rid of the 100% text column width).

### This pdf seems pretty accepta

This pdf seems pretty acceptable, but then I am quite happy to read programming-related resources on my screen.

### It's not pdf, per se

It's not pdf, per se, but rather nicely formatted text (I suppose I should have been more clear, but most pdfs I've downloaded use some form of typesetting, whether done by the author, or by default by the document creation software). If I want a pdf, all I need to do is save the page to a pdf and I'm done (well, not quite, if there are a number of parts, then I either need to print them all individually or process them with something like psjoin, though for the Reader, this really isn't an issue).

The big problem tends to be formatting -- bad page breaks, poor margins, poor font control, etc. make the text harder to read than necessary (generally a grey mass of wide, short paragraphs). Additional problems occur, for example, with pre-formatted text running past the boundary of the page. It looks fine on the (much wider) screen, but is cut off when printed (granted this can happen with say, LaTeX, but there you can see beforehand how the page will print, and correct it). Other minor issues arise with things like color -> grayscale conversions (e.g. try printing the Alice ML manual and tell me where all the hyperlinked text went to...).

Again, while it's still possible to make all of these mistakes with one of the *TeXs, you have to go out of your way to screw things up with them, as even a plain vanilla LaTeX article class document is much more readable than an HTML dump to pdf.

-30-

### Some specifics

I suppose I should have done this earlier, but looking at the PDF you made, I can give a few more specific examples of where better typesetting would help:

1: The margins are far too small. This causes the text to overwhelm the page, and makes it hard to read. Look, for example, at page 31 -- it's a grey monolith... Something interesting to note here in that the large font actually makes things a bit nicer, as it cuts down on the number of words per line and makes the paragraphs taller, increasing readability.

2: Unnecessary extras, like the images and underlined text of external links overly clutters the page. Look at page 29 for a prime example of this.

3: Lack of an intelligent typesetting algorithm leads to things like the orphans on pages 5 and 6, widows like on page 9, and separated section heads, like on page 16.

4: Code boxes are split all over the place. Some right in the middle, like the ones on pages 6/7, and 19/20 (where two lines of code ended up split over two pages of text), some right at the end, like on page 22/23, and some like the box on pages 14/15, where the code is completed on one page, but the box completes drawing on the next page...

5: Overfull boxes. While not a big issue here, we see a small example of this on page 3, where the code examples threaten to spill over their borders.

6: Poor font control/choices cause symbols, like the * -> * on page 7 to jump out of the text (and look a bit like * _> * to boot), rather than flow with it.

7: Bad things like the table on page 33 happen...

8: We can really do without things like the WikiWordHeadingForEachArticle, can't we?

Anyway, I think you get the point.... And while these things may seem small, they do have a large overall effect on the readability of the documents. It was said quite well in the documentation for the LaTeX Memoir class

The essence of good typography is that it is not noticeable at first, or even second or later, glances to any without a trained eye. If your initial reaction when glancing through a book is to exclaim about its layout then it is most probably badly designed, if it was designed at all. Good typography is subtle, not strident.

...

However, just as writing is a skill that has to be learned, typography is also an art that has to be learned and practised. There are hundreds of years of experience embodied in the good design of a book. These are not to be cast aside lightly...

-30-

### Understood

Thanks, I fully understand your reasoning. I imagine it takes a lot of work to publish a decent looking magazine using LaTeX (especially if you nor all authors know LaTeX).