[reportlab-users] Bulleted Text not displaying

[Peter Mattingly]

"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<http://en.wikipedia.org/wiki/TiddlyWiki>and
DokuWiki <http://en.wikipedia.org/wiki/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

>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://two.pairlist.net/pipermail/reportlab-users/attachments/20081017/83329fe4/attachment.htm>