[reportlab-users] Bulleted Text not displaying

[adam hyde]

hi

Would you consider using FLOSS Manuals for the docs?

We have a good system in place, and we use Reportlab to gen the PDF for
print ready source:
http://www.flossmanuals.net


adam


On Fri, 2008-10-17 at 18:03 -0700, Peter Mattingly wrote:

> "But i our favour, we do have a broadly accurate user guide, the

> source to create it, and a ton of readable, working tests"

> 

> 

> Granted.  As much as I harp on the lack of documentation, this

> documentation is miles above any other open source documentation I've

> ever seen; With the statistically anomolous exception of larger

> projects: Samba, Mplayer, Apache, etc; Which have financial backing in

> some fashion, for the most part.

> 

> "The only workable solution is a community effort, which I have been

> pleading for on this list for years."

> 

> 

> Nerd's aren't good at writing, in general.  Me being the exception.  I

> had to work really hard to be as fluent with printed text as with

> words; To be fair I have an unfair advantage of being naturally

> pre-disposed to this type of discourse.

> 

> "The source to the docs has been in every distro since launch until,

> oh, about 3 weeks ago (you have to use svn now).  They are just Python

> scripts.  This was our criterion for release 1."

> 

> 

> I didn't mean that this was the first I've heard of doc patching in

> *this* project, really in *any* project.  Finding any dedicated effort

> to create documentation for anyone with an open source project is

> laudible.  And asking for user input on documentation?  I've never

> even heard of any dev *proposing* such; They'll just bang something

> together at the last minute, spelling, gramatically and factual errors

> included; Rife with "...this should be obvious..." and other

> wearisomly predictable and unhelpful catchisms that make their

> projects terrible to behold.  So when I say "This was the first I've

> heard..." really it's worse than you thought.

> 

> "If someone finds that the user guide doesn't explain something

> clearly enough, and has *an hour to spare*, it would be great if they

> could either (a) send in a *patch correcting or expanding it* (i.e. 20

> lines to generate the right paragraphs in the guide); or (b) send in a

> *test script or teaching example*.  We can review and check these

> things quickly."

> 

> 

> Emphasis mine.  So you're saying: if I want to "patch" (e.g. revise or

> completely re-write from the ground up) a segment of documentation I

> have to send in code?  Before I say anything more about that, let me

> quote from the user guide for a second:

> 

>         *The two attributes spaceBefore and spaceAfter do what they

>         say*, except at the top or bottom of a

>         frame. At the top of a frame, spaceBefore is ignored, and at

>         the bottom, spaceAfter is ignored. This

>         means that you could specify that a 'Heading2' style had two

>         inches of space before when it occurs in

>         mid-page, but will not get acres of whitespace at the top of a

>         page. These two attributes should be thought of

>         as 'requests' to the Frame and are not part of the space

>         occupied by the Paragraph itself.

>         

>         *The fontSize and fontName tags are obvious*, but it is

>         important to set the leading. This is the

>         spacing between adjacent lines of text; a good rule of thumb

>         is to make this 20% larger than the point size.

>         To get double-spaced text, use a high leading. If you set

>         autoLeading(default "off") to "min"(use

>         observed leading even if smaller than specified) or "max"(use

>         the larger of observed and specified) then an

>         attempt is made to determine the leading on a line by line

>         basis. This may be useful if the lines contain

>         different font sizes etc.

> (Page 62 of the user guide, section 6.1 )

> 

> 

> "The two attributes spaceBefore and spaceAfter do what they say"

> 

> Oh they do, do they?

> 

> So in this context we're talking about Paragraphs and their associated

> style's correct?  So a style would dictate certain properties of the

> Paragraph and the text they contain right?  So spaceBefore and

> spaceAfter provide some variables for manipulating space having to

> deal with the paragraph; But what space?  Perhaps spacing between

> letters in the text?  Vertical space between paragraphs?  Horizontal?

> Spacing between lines of the text in the paragraph?  Something else?

> 

> From the rest of the text it's implied that this is padding within the

> frame surrounding the paragraph.

> 

> You can see where some of my frustration comes from.

> 

> Now here, I'll provide a little rewrite for the second case I've

> cited:

> 

>         The fontSize and fontName attributes, set size of the font

>         being used (e.g. size 12, 16, 20, etc) and the name of the

>         font being used when creating text (e.g. Times New Roman,

>         Verdana, etc) respectively.

> 

> It isn't perfect and probably could use some revision and editing.

> But it's quite a lot better than "The fontSize and fontName tags are

> obvious".  But in order to submit my revision I have to figure out how

> to embed it in Report Lab programming code?  That's ridiculous.

> 

> I'm currently a student learning how to do more with Report Labs, I'm

> not experienced enough with your conventions to create clean portable

> code.  But at the same time, I'm able to revise and elucidate a

> section of the user manual with perfect clarity and a few minutes

> time.  This would not be the case with programmtically creating a

> similar solution.  If the time I've spent so far is any indication,

> such a project would require *multiple hours* of work to fully

> understand the entire process.  I suspect I've found an inefficiency

> in the process of the community driven documentation you're trying to

> create.

> 

> I can however make changes to a Wiki, which is a much simpler approach

> that others have taken to create community editable documents -

> including user documentation.  The experience is akin to making a post

> on a forum or writing a letter, rather than programming.

> 

> I would recommend Media Wiki (http://www.mediawiki.org/wiki/MediaWiki)

> which is used with Wikipedia.  If that's too much administrative

> overhead (too much for me at least!), you can use any one of these

> others:

> 

> http://en.wikipedia.org/wiki/Comparison_of_wiki_software

> 

> Some of the better solutions are TiddlyWiki and DokuWiki for a simpler

> approach.  I'm running DokuWiki and I'm very happy with it.  I've

> heard nothing but good things about TiddlyWiki.

> 

> Thank you for taking the time to talk with me about these issues.  I

> hope to be of some help in the future.  Report Labs is one of the few

> programmatically accesible methods I've found for creating highly

> formatted output for more than report creation; Which seems to be all

> that other techies seem to aspire their output to be. ><

> 

> 

> On Mon, Oct 13, 2008 at 11:24 PM, Andy Robinson <andy at reportlab.com>

> wrote:

>         2008/10/13 Peter Mattingly <pmattingly at mail.csuchico.edu>:

>         > You know what I mean though?  Sufficient technical

>         documentation is one huge

>         > hurdle that OSS in general has to get over before any sort

>         of general (read:

>         > Non-maddeningly frustrating) adoption can take place.

>         

>         

>         You're correct; it is a weakness.  (But i our favour, we do

>         have a

>         broadly accurate user

>         guide, the source to create it, and a ton of readable, working

>         tests).

>           But it also

>         takes a heck of a lot of time - more than maintaining

>         the code does.  It's not just documenting new features, it's

>         constantly

>         pruning and editing everything which may be affected by a

>         change.  The only

>         workable solution is a community effort, which I have been

>         pleading for on this

>         list for years.

>         

>         >

>         > And...you can patch the docs?  First I've heard of doing

>         that...

>         

>         

>         The source to the docs has been in every distro since launch

>         until,

>         oh, about 3 weeks ago (you have to use svn now).  They are

>         just Python

>         scripts.  This was our criterion for release 1.

>         

>         If someone finds that the user guide doesn't explain something

>         clearly enough,

>         and has an hour to spare, it would be great if they could

>         either (a) send

>         in a patch correcting or expanding it (i.e. 20 lines to

>         generate the right

>         paragraphs in the guide); or (b) send in a test script or

>         teaching example.

>         We can review and check these things quickly.

>         

>         

>         Best Regards,

>         

>         --

>         Andy Robinson

>         CEO/Chief Architect

>         ReportLab Europe Ltd.

>         165 The Broadway, Wimbledon, London SW19 1NE, UK

>         Tel +44-20-8544-8049

>         

>         _______________________________________________

>         reportlab-users mailing list

>         reportlab-users at reportlab.com

>         http://two.pairlist.net/mailman/listinfo/reportlab-users

>         

> 

> 

> _______________________________________________

> reportlab-users mailing list

> reportlab-users at reportlab.com

> http://two.pairlist.net/mailman/listinfo/reportlab-users

-- 
Adam Hyde
Founder FLOSS Manuals
http://www.flossmanuals.net