On Tue, 2005-08-09 at 16:43 +0200, Hinrich Schmieta wrote: > Am Mon, 08 Aug 2005 12:28:39 -0500 hat Janet M. Swisher > <[EMAIL PROTECTED]> geschrieben: > > > Hinrich Schmieta wrote: > > > >> Hi Rick, > >> > >> I have a comparable problem when quoting code. > >> The template style OOoComputerCode makes the code hard to read. > >> A courier font in a smaller size then 12 point with a light grey > >> background would be my preference. Line numbering could be helpfull as > >> well. > >> > >> Regards > >> Hinrich > >> > >>> What is the convention we are using for quoting blocks of code? I am > >>> writing the Calc chapter on macros and I want to be able to refer back > >>> to the code with a standard reference like 'figure 1', 'table 1'...etc. > >> > > Hi Hinrich, > > > > Can you tell me in more detail why you find the OOoComputerCode style > > hard to read? I find it more common that people complain about *smaller* > > point sizes being hard to read, not larger ones. > > > Hi Janet, > the idea of a smaller font is that it would allow better to reproduce the > original formatting of the computer code. In the document I am working on > I have lots of additional line breaks only because of the 'big' > OOo-formating. Most programmers are aiming to give their code a > meaningfull format. Indenting if-clauses is a common and simple example. > The original format usually makes the structure of the code more visible > and clearer. Any additional line break is confusing here, especially for > learners. > Screenshots from the quoted blocks of code would be ideal for keeping the > format, but users would not be able to copy and paste the code for their > own purposes. > > > What leads you suggest a gray background? Would that make the computer > > code itself easier to read, or just set it off from the regular text of > > the document? > May be it is a convention I got used to, yes a grey background clearly > sets off the code from the rest of the document. > > > > > It would be possible to add support for numbering lines of code, but it > > would require updating our template, which isn't likely to happen soon. > > OOo Writer supports line numbering, but by default it numbers all the > > lines in the document. We'd have to change all our paragraph styles > > except OOoComputerCode to turn off the "Include this paragraph in line > > numbering" option. > Line numbering would be very helpfull when explaining for example where to > change the code to connect to a special database in the users system.
I agree that line numbering and good formatting would be good especially with 'real' programming code. Languages like Python rely on line breaks and indentation, and, of course, formatting makes the code more readable. I also like the gray background color idea (10% or less?). But what about the border -- a basic line, or? My needs would be for simple code examples that do not need much formatting, such as when displaying formulas or very simple 1 to 5 line macros. But I would also vote for a more complex style that could support 10 to 20 lines of programming code properly formatted with line numbers for easy reference. I may even need to use this for my work. For a caption "Code example" or "Macro example" would generally work...unless I am explaining formulas...Then "Formula example". I guess as long as the caption is consistent within the chapter and the context of the writing any of these would be good. Can anyone think of one "catchall" caption? Should we pass around a document with a 'code box' style for comments and consensus? -- Regards, Rick Barnes www.nostabo.net Read my blog: http://www.nostabo.net/blog/index.php ******************************************************************* PRIVILEGED - PRIVATE AND CONFIDENTIAL This electronic mail is solely for the use of the addressee and may contain information which is confidential or privileged. If you receive this electronic mail in error, please delete it from your system immediately and notify the sender by electronic mail or using any of the contact details noted herein. This e-mail sent via Evolution 2.2.1 running on a Linux 2.6.12 kernel.
signature.asc
Description: This is a digitally signed message part
