ext call doco warts

[mwhudson]

BPO	493243
Nosy	@mwhudson, @freddrake
Files	ref5-2.diff: another go.

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/freddrake'
closed_at = <Date 2002-06-20.14:25:27.000>
created_at = <Date 2001-12-14.10:22:49.000>
labels = ['docs']
title = 'ext call doco warts'
updated_at = <Date 2002-06-20.14:25:27.000>
user = 'https://github.com/mwhudson'

bugs.python.org fields:

activity = <Date 2002-06-20.14:25:27.000>
actor = 'fdrake'
assignee = 'fdrake'
closed = True
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2001-12-14.10:22:49.000>
creator = 'mwh'
dependencies = []
files = ['250']
hgrepos = []
issue_num = 493243
keywords = []
message_count = 8.0
messages = ['8174', '8175', '8176', '8177', '8178', '8179', '8180', '8181']
nosy_count = 2.0
nosy_names = ['mwh', 'fdrake']
pr_nums = []
priority = 'high'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue493243'
versions = []

[mwhudson]

Now they've been compiled <wink>, I notice that there
are some warts in my docs for the *- and **-style call
syntax.

1. the "argument_list" production is really, really
   confusing. there must be a better BNF-style way of
   saying that. I don't think vertically centering the
   production name against the production helps.

2. For some reason, where I say

It is unusual for both keyword arguments and the
"*expression"syntax to be used in the same call, so in
practice this confusion does not arise.

there's no space between "*expression"' and syntax'.
I'd guess that this is because in the source, the
\samp{} macro is the last thing on the line, but why
that should lead to a missing space is beyond me --
more latex2html bugs?

(just noticed the same thing a bit higher up too --

the "**expression"argument, if any

No hurry with these.

[freddrake]

Logged In: YES
user_id=3066

Fixed table cell alignment in Doc/perl/python.perl revision
1.115.

Fixed item 2: Worked around spaces problem in
Doc/ref/ref5.tex 1.53

This bug remains open; I still need to address the basic
problem in item 1 (confusing pseudo-EBNF).

[mwhudson]

Logged In: YES
user_id=6656

Another problem with the pseudo-EBNF: it's wrong. Oops.

It suggests that f(a, **b) isn't legal, for example.

I've attached an attempt I think it right, but I'm not sure
and haven't compiled it (& so don't know if it looks any less
confusing than last time).

[mwhudson]

Logged In: YES
user_id=6656

I'm going to check my fix in unless someone complains *real*
soon.

At least I know it compiles now, and I think it's an
improvement.

[freddrake]

Logged In: YES
user_id=3066

Bumped priority; needs review.

[freddrake]

Logged In: YES
user_id=3066

1. Do you still see vertical centering of the production
   name? That should be aligned with the top of the definition
   text. I've played contortionist with that production in
   Doc/ref/ref5.tex revision 1.62.

2. That's not another bug, that's the one that keeps biting
   us. I'm not sure whether that's in latex2html itself or in
   my extension code for it. ;-( This has already been fixed
   on the trunk.

I'm closing this, since I think we're ok now; feel free to
re-open or file a new report if you think my changes aren't
sufficient.

[mwhudson]

Logged In: YES
user_id=6656

Sorry, you need to reread my comment of 2001-12-20: the
problem with the pseudo-BNF as it stands is that it is
WRONG! This is what my patch attempts to fix.

The problems mentioned originally have been fixed -- perhaps
I should have opened a new report.

[freddrake]

Logged In: YES
user_id=3066

Ok, I've fixed that with a different patch. Checked in as
Doc/ref/ref5.tex revision 1.63.

Thanks for your patience, and persistence!