Что пишут в разделе BUGS в документации


В документации есть секция BUGS, которая, согласно man(7), предназначена для описания различных известных проблем:

Known bugs, limitations, and work-arounds should be described in this section.

Но разработчики её используют по-разному. Одни используют по назначению и пишут ограничения, иногда с воркэраундами, как например здесь:

calendar.1

calendar doesn’t handle all Jewish holidays or moon phases.

grolj4(1)

Small dots.

pppd(8)

Scripts should be run as root, but are not.

ps(1)

Since ps cannot run faster than the system and is run as any other scheduled process, the information it displays can never be exact.

rs.1

There are too many options.

script.1

script places everything in the log file, including linefeeds and backspaces. This is not what the naive user expects.

units.1

The effect of including a ‘/’ in a prefix is surprising.

wsfontload(8)

Many features are missing. There is no way to remove a loaded font.

newsyslog(8)

Does not yet automatically read the logs to find security breaches.

spell.1

British spelling was done by an American.

Это явно писал перфекционист: “Программа работает, но не совсем хорошо.”:

cu(1)

This program does not work very well.

bash(1)

It’s too big and too slow.

akbd.4

The list of built-in mappings doesn’t follow any logic. It grew as people submitted what they needed.

…упоминание нерадивых вендоров и паршивых стандартов:

apm.4

Not all the BIOSes support power down the way we are attempting to execute it. Not all BIOS vendors even read the specification.

openssl.1 pkcs12(1)

Some would argue that the PKCS#12 standard is one big bug :-)

vic(4)

There are tons of bugs in VMware and the underlying host operating systems. Please consider that the security of the OpenBSD guest can be circumvented by attacking the host environment.

…недостатков самой документации:

ipcs(1)

This manual page is woefully incomplete, because it does not at all attempt to explain the information printed by ipcs.

Mail.1

There are some flags that are not documented here. Most are not useful to the general user. Usually, mail and mailx are just links to Mail, which can be confusing.

screencapture(1)

Better documentation is needed for this utility.

lseek(2)

This document’s use of whence is incorrect English, but is maintained for historical reasons.

sigvec(2)

This manual page is still confusing.

rtnetlink.3

This manual page is incomplete.

Кто-то признает в своём коде наличие багов:

vi(1)

Probably. See “:help todo” for a list of known problems. Note that a number of things that may be regarded as bugs by some, are in fact caused by a too-faithful reproduction of Vi’s behaviour. And if you think other things are bugs “because Vi does it differently”, you should take a closer look at the vi_diff.txt file (or type :help vi_diff.txt when in Vim). Also have a look at the ‘compatible’ and ‘cpoptions’ options.

festival(1)

More than you can imagine.

tip.1

Probably plenty.

mongoose.4

Has some.

perlplan9(1)

“As many as there are grains of sand on all the beaches of the world…” - Carl Sagan

а кто-то всё еще считает, что их нет (почему-то такое в основном в документации для Perl):

perlbug(1)

None known (guess what must have been used to report them?)

perlrequick(1)

None.

perlthanks(1)

None known (guess what must have been used to report them?)

dot_clean(1)

None known.

CGI::Cookie(3pm)

This section intentionally left blank.

Только один раз я видел, чтобы в документации отсутствие теста считалось недостатком, это было в urandom(4):

No randomness testing suite provided.

Проблемы совместимости описывались только в talk.1:

The version of talk released with 4.3BSD uses a protocol that is incompatible with the protocol used in the version released with 4.2BSD.

Шуточки разработчиков Perl:

perl(1)

Perl actually stands for Pathologically Eclectic Rubbish Lister, but don’t tell anyone I said that.

Иногда секция BUGS описывает планы на будущее и текущий статус. И тогда некоторые утилиты только подтверждают пословицу “Нет ничего более постоянного, чем временное”: планы на будущее не сбываются (или это будущее ещё не наступило?).

rlogin(1)

The rlogin utility will be replaced by telnet(1) in the near future.

UKC(8)

The add command is rather restricted, and might be expanded in the future.

pkg_check(8)

Work in progress. The order of checks is not definitive, and more checks may be added. Use with caution.

grohtml(1)

Grohtml has been completely redesigned and rewritten. It is still beta code.

fsck_msdos.8 (OpenBSD Mac OS)

fsck_msdos is still under construction.