On Nov 16, 2013, at 6:30 PM, Leif Hedstrom <[email protected]> wrote: > > On Nov 16, 2013, at 5:46 PM, Leif Hedstrom <[email protected]> wrote: > >> >> >> which seems reasonable. However, I have a few questions on this: > > Bah, email ate my formatting. This is how I wanted the questions to look: > > * Do we create one page / file for every plugin API? Or do we try to group > them together by some logic (things logically belonging together, like > TSmalloc and TSfree)?
We group them, otherwise there would be too much boiler plate and man pages would proliferate like bunnies. > If there's a group, what do the file get named, Choose what you think the most sensible name is. For real man pages, we could link them by all the names, but that's probably tricky with Sphinx. > and how do we make the grouping such that we all agree and work on the same > grouping? I used my judgement and no-one has complained yet. > > * How does this relate to the docs in docs/sdk, e.g. docs/sdk/mime-headers? > Do we add or change links / referencesin docs/sdk over to the reference/api > sections? Reference docs are for reference. The SDK docs are for exposition and tutorial material. > > * Do we also have to produce a man page, or is that what reference/api is all > about? Everything in reference/ produces a man page. > Poking around some more, I see several pages which does the grouping. As > such, I'm wondering if e.g. TSUrlCreate.en.rst should be renamed to just > TSUrl.en.rst ? And if that's the case, we ought to put all TSMimeHdrField* > APIs into one page, TSMimeHdrField.en.rst ? That's a judgement call. Just do what you think is best. > Looking at the list, the natural grouping / renaming (of what we have) would > be > > TSHttpParser > TSHttpTxnMilestone > TSIOBuffer > TSMBuffer > TSPlugin > TSRemap > TSUrl > > Other sections would probably look nicer with a more generic / descriptive > title, e.g. "Debugging", "Hooks", "Remap Plugins", "Life Cycles" etc. But > then maybe the above ought to be renamed too, e.g. "HTTP Parser", "Milestone > metrics" and other descriptive names. These are section 3 man pages, so name them after the "root" API. Typing "man HTTP\ Parser" is not going to work well. J
