search

melisgl / mgl-pax

Documentation system, browser, generator.
https://melisgl.github.io/mgl-pax-world/
MIT License
75 stars 13 forks source link

@sections no longer exported #30

Closed mariari closed 1 year ago

mariari commented 1 year ago

On the newest version of quicklisp the @ documentation are no longer exported, causing a regression in my system.

melisgl commented 1 year ago

In e0b7417, PAX was changed to not exporting SECTIONs and GLOSSARY-TERMs by default (see https://melisgl.github.io/mgl-pax-world/pax-manual.html#MGL-PAX:EXPORTABLE-REFERENCE-P%20GENERIC-FUNCTION). The default was changed because in most cases the names of sections are not part of the contract (i.e. they are subject to change) and exporting them can lead to package conflicts. Plus, with the @SECTIONNAME naming convention, one can list e.g. all PAX sections by typing "PAX::@" and pressing TAB in Slime. See the example in the linked documentation for how to override the default, maybe on a per-package basis.

I've been going back and forth on whether to export documentation since forever. Can you elaborate on what kind of regression this causes?

mariari commented 1 year ago

Thanks, I wasn't sure if it was a mistake, since I've been using the old behavior.

I just got a report this morning that an older version of the software I maintain no longer built, this was because I ended up qualifying a pax @section in one spot.

https://github.com/anoma/geb/commit/4001de80c3da06e23dc323f8f4a4da582316b39c

was the patch that fixed it, namely I just exported all of the pax sections, to make my life easier so I didn't have to qualify it all over the place.

I'm not against the new behavior, just caught me off guard when an old tagged release stop building

melisgl commented 1 year ago

Thank you. I'm closing this issue, then.

In general, there is no way around the fact that [the structure of] the documentation may or may not be part of interface. I'm considering exporting only the top-level section and maybe some crucial and stable glossary entries in my libraries, but I'm still a bit on the fence ...