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: ```python assignee = 'https://github.com/freddrake' closed_at = created_at = labels = ['docs'] title = 'ext call doco warts' updated_at = user = 'https://github.com/mwhudson' ``` bugs.python.org fields: ```python activity = actor = 'fdrake' assignee = 'fdrake' closed = True closed_date = None closer = None components = ['Documentation'] creation = 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"' andsyntax'. 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!