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.
