On May 30 04:04:28, martinw...@gmail.com wrote: > On 5/30/24 00:03, Jan Stary wrote: > > > I very much doubt anyone uses libsox at all. > In fact, I was looking for something that uses libsox today, and the only > Debian packages that depend on it are sox and sox-fmt-* (!) Maybe I should > use it for sound file reading, just to be the only one, but unfortunately it > only delivers (and requires) 32-bit signed samples, which is a bit lumpy. I > guess it wins if you want effect chains. > > but libsox(3) itself says > > > > This manual page is both incomplete and out of date. > > > Is the Doxygen documentation any better? > > Far more detailed/complete and less likely to get out of sync if, say, a > field is added to a structure, so I guess we should check that libsox.3 is > up to date,
We know it isn't. > but including all the stuff in soxygen seems like a lot of work > and would result in an enormously long page Yes, someone needs to actualy write write manpage, preferably someone who knows and uses libsox. I don't. And I suspect nobody does. I naively asume that an actual user of libsox would read this mlist - if you exist, please speak up. (That's not trying to coerce you into writing the manpage, that's to find out whether it has any users.) Failing that, I would even stop shipping the library, (including the non-documentation) and just ship the binary. > and libsox.7 gives an overview of how to use it, It is suppsosed to describe the entire API. > which the doxygen output lacks. Can the doxygen stuff by > amplified to include that, and can a reasonable manual page > be generated out of the doxygen output? Even if it can, I am very strongly opposed to that. Tha manual page is the stadard format of documentation. The auto-generated manpages (by docbook or doxygen or whatnot) tend to be of _abyssmal_ quality. > I dunno, I also like being able to zip through structures, their fields and > their types interactively rather than having to wade through header files. > Maybe if the doxygen output were on the web it might attract more users. Please, no. Let's have a normal manpage (if there is any point to even documenting libsox at all). Look for instance at https://man.openbsd.org/sio_open That's an almost perfect example of a single manpage documenting an entire API (namely the OpenBSD audio interface). That's what I have in mind; but I don't even use libsox, nobody does. > However, for the moment let's aim at 14.2.3, Eh, we have 14.4.2 already :-) > making sure all CVE and other > bug fixes are included, fixing any other critical bugs and making a > distro-friendly release of what we have already. Let's give it another nine years. > Then we can think about > 14.3 adding functionality (backwards-compatible please!) but I don't see > removing stuff as a priority unless it is a burden of some kind I very much see the current build system as a burden that needs to be removed/replaced; that's why I started with that. Grep for HAVE_* and go through them all; I did, last night. SoX is very much a child of the early nineties, and the current build system caters to that, checking all over the place whether you have e.g. mkstemp() or stdint.h, like it's 1991. SoX implements its own strcasecmp() for crying out loud. Catering to that is the opposite of my intention. > and I see the doxygenness of sox.h as a good idea > that was never seen through to its proper conclusion. It hasn't been touched since 14.4.0 (in 2012). Jan _______________________________________________ SoX-devel mailing list SoX-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/sox-devel
