Re: Help needed on porting ripgrep-all

Hello Aisha and Sebastian,

A Tammy wrote on Thu, Sep 12, 2024 at 09:18:37AM -0400:
> On 9/12/24 9:16 AM, A Tammy wrote:
>> On 9/12/24 9:08 AM, Neel chakraborty wrote:

>>> Thank you, that solves the problem. 
>>> Can you please tell me how you figured out 
>>> `MODCARGO_CRATES_KEEP = libsqlite3-sys`
>>> would solve the problem?
>>>
>>> I read through cargo-module(5), but couldn't find 
>>> MODCARGO_CRATES_KEEP

>> Hmm, it might be time to add this to cargo-module(5). If you want to
>> add a patch for adding this to the man page, it would be very welcome :)

> From semarie@ email, maybe we shouldn't add it to the man page, so lets
> ignore this for now.

In general, i feel that if a feature is visible in the UI,
is deliberately supported, and there is at least one case
where it sees good use, and even more so if multiple good uses exist,
even if the number is small, documenting the feature is worthwhile.

If it sees good use once, chances are a second case may eventually
arise where it is needed. How, then, are people supposed to
discover the feature if it is deliberately undocumented? Isn't
that exactly the trap Neel feel into?

Also, suppose somebody reads a ports Makefile using that feature.
How are they supposed to understand what is going on, and why the
author writing the Makefile chose to use an undocumented feature?
Telling people to Read The Fantastic Source Code is just fine
when they want to hack on the code or learn in general; telling
them that when they merely want to use that code is less than
friendly.

If a feature is not intended for general consumption, the
documentation should explicitely say so, explain why the features
is only provided as a last resort, and provide a recommendation
what to use instead for more typical needs.


I believe that completeness is one of the core virtues of
documentation, alongside correctness, clarity, conciseness,
consistent style and structure, and constistent markup.

Deliberately leaving a feature undocumentated ought to be reserved
for cases where all of the following hold:
* The feature is completely useless or so egregiously ill-designed
that it would be better if it had never been invented.
* There is no good reason for anyone to ever use it.
* It is unused in the OpenBSD tree, or it is used extremely rarely
and there are plans to exterminate all the remaining uses.

At least that's what i do in LibreSSL documentation, a region
of our manuals that still resembles Swiss cheese, and a library
that boils over with API elements intended to serve unusual
purposes - some exotic, some obscure, some misguided, some
downright absurd.

Yours,
Ingo

NB: The above does not apply to kernel documentation.
Section 9 of the manual is intentionally selective.