On Sat, Feb 19, 2011 at 10:34 PM, Pieter Hintjens <p...@imatix.com> wrote:
> On Sun, Feb 20, 2011 at 6:22 AM, David Kantowitz <dkantow...@gmail.com> > wrote: > > > Oddly I find the current format of http://api.zeromq.org/ much easier to > > read. I realize all the text is the same, but something about the old > man > > page formatting is just easier on my eyes. > > The red is harder to read, for sure, this is the house style but I'm > not sure it's ideal for the man pages. But consistency is perhaps > best, I certainly get used to the color scheme and the blue then seems > odd. > The darker red color is much better (same readability for me as the blue in the old docs). More things I noticed. Some of these seem like small issues. I use the documentation a lot, so even small things that make the man pages less readable are frustrating to me. Also, I just mention one or two pages where I see a formatting issue. The same issue usually happens throughout the documentation. 1) Using list items when the list has only a single line results in poor line spacing and the bullet is distracting while adding no visual clarity. This can easily be seen comparing the new and old zmq(7) and zmq_connect(3). 2) In zmq_connect(3) the "Note" pullout(?) did not get generated properly in the new manual. 3) The "Errors" section in new manual has each error flush to the left. The old manual approach of indenting each error was more readable. 4) In the new manual the synopsis appears in a dashed box. I like this. Really makes this very important part of the man page pop out. 5) Putting the example in the same dashed box at the bottom is much harder to read. I know it is the site style to have the big curly braces at the beginning of a code pullout, but it doesn't help. Also having the horizontal scrolling for an example box is not good (see example in zmq_pgm(7)). The old documentation avoided this with: a) narrower margins, b) no big curly braces, and c) making the whole page width wide enough so scrolling happens in the browser's outside edge scrollbars and not inside the document. 6) Looking at zmq_poll(3) there are missing zeros in the new documentation: a) Description paragraph 4, "of timeout is 0, zmq_poll()" b) Return Value paragraph 1, "revents or 0" 7) The heading for each section should be somewhat larger. Specifically the "Return value" section is hard to spot (ex, zmq_poll(3)). I typically zip down man page to see exactly what the return values are and make sure I'm handling all of them. That is much harder when I have to search around looking for that part of the man page. Regards, David K.
_______________________________________________ zeromq-dev mailing list zeromq-dev@lists.zeromq.org http://lists.zeromq.org/mailman/listinfo/zeromq-dev
