opened
zygoloid
username_0
Subject: Support programs with options that differ only by case or punctuation

### Problem
- `clang`, an open-source C/C++/... compiler, supports lots of options, and in some cases the options differ only by punctuation (`-ObjC` and `-ObjC++` mean different things, as do `-I` and `-I-`); in other cases, options contain only punctuation (`/?`). Sphinx does not support documenting such options.

#### Procedure to reproduce the problem
```
.. option:: -ObjC

Description of option ``-ObjC``.

.. option:: -ObjC++

Description of option ``-ObjC++``.
```

#### Error logs / results
```
ClangCommandLineReference.rst:9: SEVERE: Duplicate ID: "cmdoption-clang-ObjC".
```

#### Expected results
Produce distinct IDs for distinct flags. Do not assume that punctuation can be stripped. Support options containing only punctuation. Either that, or provide a mechanism to override the ID generated for a particular option name.

### Reproducible project / your project
- https://github.com/llvm-mirror/clang/tree/master/docs/ClangCommandLineReference.rst (not submitted yet, will be there shortly)

### Environment info
- Python version: 2.7.6
- Sphinx version: 1.2.2
Support programs with options that differ only by case or punctuation
issue
created
tk0miya
username_1
In my short investigation:
The option directive uses following regexp to parse given option:
```
option_desc_re = re.compile(r'((?:/|--|-|\+)?[-\.?@#_a-zA-Z0-9]+)(=?\s*.*)')
```
At present, it does not contain `+` sign. So `-ObjC++` is recognized as `-ObjC` option having `++` argument. Then it is a cause of the duplication warning.
To fix this, I would add `+` sign to the regexp. In my local, it works fine.

BTW, now we can use only `-.?@#_` signs for option name. This means the following characters could not be used:
`!"#$%&()*+,/:;<>[\]^{|}~`, ` (back quote) and any non ASCII characters.
Is this intended?
I feel we should reconsider these definition.

@username_2 any ideas?
comment
created
tk0miya
username_1
Side note:
I don't list up `=` character to the unsupported signs for option name with intent.
It is used for a delimiter of option name and argument. So it means Sphinx cannot use `=` sign for an option name. I think it is a restriction of Sphinx.
comment
created
shimizukawa
username_2
IMO, it is nice if every `string.punctuation` characters were accepted exclude `=` char.
comment
closed
tk0miya
username_1
issue
created
tk0miya
username_1
Fixed at b9bba67 and baa065f.
Only `+` sign is allowed in stable branch to keep compatibility. It will be released as 1.5.3.
And all punctuations are allowed in master branch.

Thank you for reporting.
comment