search

didierverna / declt

Reference manual generator for Common Lisp libraries
Other
38 stars 6 forks source link

Typesetting option :file-name defaults to :library-name, not system name #19

Closed snunez1 closed 2 years ago

snunez1 commented 2 years ago

The documentation for typesetting options says:

:file-name

The base name of the generated file, sans extension. It defaults to the system name.

However in the current master branch it seems to default to the value passed as :library-name. Defaulting to the system names seems a better choice.

didierverna commented 2 years ago

Thanks for the report. Why do you think that defaulting to the system name is better? The idea of defaulting to the library name was to make it easier to get a more readable file name. But I'm not holding to this very strongly though. For example, from a net.didierverna.declt system name, you may want to use Declt as library name, but you may also prefer a file name without the capital D...

snunez1 commented 2 years ago

The system name is likely to be more filesystem friendly. For example if I document "Array Operations" as the library-name, the output file has mixed cased and a space. It's still possible to use it, but a system name might be easier. In either case, the documentation should probably match the reality.

There could be an exception here though -- ASDF subsystems are supposed to use '/' as a separator, and in that case it's unlikely the filesystem will accept the name. I'm beginning to think that :filename should probably be given in all cases, and perhaps not have a default.

didierverna commented 2 years ago

OK, I've indeed come to agree that it's better to default to the system name. Given that 1. it's very rare to want to document a subsystem on its own (you're the only one I know who wants to do that :-)), and 2. it's convenient to have a default value working in most cases (e.g. Quickref does that for the 2000+ Quicklisp libraries), I think I'll keep a default value anyway.

didierverna commented 2 years ago

Done and pushed to the trunk. Thanks again for the report.