search

statnet / ergm

Fit, Simulate and Diagnose Exponential-Family Models for Networks
Other
94 stars 36 forks source link

Make proposals internal by default? #460

Open krivit opened 2 years ago

krivit commented 2 years ago

At the moment, their documentation is a part of the manual and the index displayed in HTML help. Since they are meant to operate "under the hood", we might want to change the template to give them an automatic keyword "internal" so that they are hidden. Any objections? @martinamorris , @chad-klumb , @CarterButts , @drh20drh20?

drh20drh20 commented 2 years ago

I'm not sure what benefit there is to hiding them. If there's some small chance that the unhidden docs would be useful, as there seems to be, what's the harm in keeping the status quo?

krivit commented 2 years ago

The benefit is that they don't take up space in the index and in the manual, particularly since many of them are poorly documented.

We might even want to consider similarly hiding individual term and constraint documentation, since the user can still find them via the index and then look them up as needed.

martinamorris commented 2 years ago

I'm having a bit of trouble following this. Can you pls. remind me what the "manual" and the "index" are?

krivit commented 2 years ago

Index is what you get if you type library(help="ergm"). The manual is the PDF document with all the non-internal help entries; it gets generated during package build process and/or by R CMD Rd2pdf.

krivit commented 2 years ago

I increasingly think that all termalikes should be marked internal, since they make it hard to find anything in the package index, while being easily discoverable via the ergmTerm index.