pimutils / pimutils/khal

Cannot adjust line warning in generated man page

Open
#598 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type: bug type: documentation
Dominant language
Python
Stars
3.1k
Forks
233
Avg merge
1h 44m
Merged PRs (30d)
1

Description

During work on Debian package of khal 0.9.2 I hit warning about man page which can be reproduced easily:

LC_ALL=3Den_US.UTF-8 MANROFFSEQ=3D'' MANWIDTH=3D80 man --warnings -E UTF-8 =
-l -Tutf8 -Z build/man/khal.1 >/dev/null

resulting in:

<standard input>:101: warning [p 1, 9.7i]: cannot adjust line
<standard input>:1424: warning [p 14, 2.7i]: cannot adjust line

First line that cannot be adjusted is reference to python's str.format which can be simply removed but second one is from generated rst file (default option of one config parameter).

Unfortunately I wasn't able to find out why this is happening. Workaround is
eg. to add .nf before affected paragraph to avoid wrapping it.
But I didn't find out (by even digging into sphinx.writer.manpage code and khal's config generator) how to force Sphinx to do so - it may be a bug in Sphinx manpage generator as well but this error didn't happen with khal 0.8.x.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the warning with the command shown against build/man/khal.1, then inspect the referenced Sphinx manpage writer and khal's config generator. Determine why the two affected paragraphs cannot be adjusted and confirm the generated man page completes without these warnings while preserving the documented text.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.