| Message ID | b0bb2e8051f19ec47140fda6500e092e37c6bea8.1624314293.git.me@ttaylorr.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | multi-pack reachability bitmaps | expand |
On Mon, Jun 21 2021, Taylor Blau wrote: > Even though the 'TECH_DOCS' variable was introduced all the way back in > 5e00439f0a (Documentation: build html for all files in technical and > howto, 2012-10-23), the 'bitmap-format' document was never added to that > list when it was created. > > Prepare for changes to this file by including it in the list of > technical documentation that 'make doc' will build by default. > > Signed-off-by: Taylor Blau <me@ttaylorr.com> > --- > Documentation/Makefile | 1 + > 1 file changed, 1 insertion(+) > > diff --git a/Documentation/Makefile b/Documentation/Makefile > index f5605b7767..7d7b778b28 100644 > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -90,6 +90,7 @@ SP_ARTICLES += $(API_DOCS) > TECH_DOCS += MyFirstContribution > TECH_DOCS += MyFirstObjectWalk > TECH_DOCS += SubmittingPatches > +TECH_DOCS += technical/bitmap-format > TECH_DOCS += technical/hash-function-transition > TECH_DOCS += technical/http-protocol > TECH_DOCS += technical/index-format As a mostly aside I've got a local series queued up to move all of these "format" docs to e.g. gitformat-bitmap(5), i.e. to make them first-class manpages, so other pages can link to them. Right now we mostly don't, but when our manpages do they link to the generated HTML, which e.g. I don't have installed by default. So since you're linking to it: Does anyone prefer this state of a affairs, and isn't it mainly useful for built docs such as https://git-scm.com/docs/git-multi-pack-index. But there's still (but maybe later in this series) a link to bitmap-format anywhere from another manual page (but there is for e.g. technical/pack-format.html).
On Fri, Jun 25, 2021 at 01:35:48AM +0200, Ævar Arnfjörð Bjarmason wrote: > As a mostly aside I've got a local series queued up to move all of these > "format" docs to e.g. gitformat-bitmap(5), i.e. to make them first-class > manpages, so other pages can link to them. Right now we mostly don't, > but when our manpages do they link to the generated HTML, which e.g. I > don't have installed by default. It would be nice to be able to look it up with "man 5 gitformat-bitmap". I actually don't have strong feelings about this particular patch getting picked up or not, since it doesn't add the actual format changes to the file itself. This does pick up the bitmap-format document in "make -C Documentation html", which is nice(r than "make -C Documentation technical/bitmap-format.html" IMHO). > But there's still (but maybe later in this series) a link to > bitmap-format anywhere from another manual page (but there is for > e.g. technical/pack-format.html). No, I didn't add any links pointed at bitmap-format. Thanks, Taylor
On Wed, Jul 14 2021, Taylor Blau wrote: > On Fri, Jun 25, 2021 at 01:35:48AM +0200, Ævar Arnfjörð Bjarmason wrote: >> As a mostly aside I've got a local series queued up to move all of these >> "format" docs to e.g. gitformat-bitmap(5), i.e. to make them first-class >> manpages, so other pages can link to them. Right now we mostly don't, >> but when our manpages do they link to the generated HTML, which e.g. I >> don't have installed by default. > > It would be nice to be able to look it up with "man 5 gitformat-bitmap". > I actually don't have strong feelings about this particular patch > getting picked up or not, since it doesn't add the actual format changes > to the file itself. > > This does pick up the bitmap-format document in "make -C Documentation > html", which is nice(r than "make -C Documentation > technical/bitmap-format.html" IMHO). Oh yes, I'm not saying don't add the target. Just a musing on how we ended up with such a large set of things in "Documentation/technical/*" as opposed to just man pages. I guess if there's good reasons for it they'll come out if/when I submit that series... >> But there's still (but maybe later in this series) a link to >> bitmap-format anywhere from another manual page (but there is for >> e.g. technical/pack-format.html). > > No, I didn't add any links pointed at bitmap-format. I see https://git-scm.com/docs/bitmap-format has somehow managed to get indexed by Google, perhaps through some magic :)
On Mon, Jun 21, 2021 at 06:25:07PM -0400, Taylor Blau wrote: > Even though the 'TECH_DOCS' variable was introduced all the way back in > 5e00439f0a (Documentation: build html for all files in technical and > howto, 2012-10-23), the 'bitmap-format' document was never added to that > list when it was created. > > Prepare for changes to this file by including it in the list of > technical documentation that 'make doc' will build by default. OK. I don't care that much about being able to format this as html, but I agree it's good to be consistent with the other stuff in technical/. The big question is whether it looks OK rendered by asciidoc, and the answer seems to be "yes" (from a cursory look I gave it). -Peff
On Thu, Jul 15, 2021 at 12:58:00AM +0200, Ævar Arnfjörð Bjarmason wrote: > >> But there's still (but maybe later in this series) a link to > >> bitmap-format anywhere from another manual page (but there is for > >> e.g. technical/pack-format.html). > > > > No, I didn't add any links pointed at bitmap-format. > > I see https://git-scm.com/docs/bitmap-format has somehow managed to get > indexed by Google, perhaps through some magic :) Presumably somebody somewhere mentioned it (if not, the list archive now links to it ;) ). The git-scm.com site doesn't use our Documentation/Makefile, so it has been building the bitmap-format page for a while. It doesn't look correct, though (it is missing everything before the "on-disk format" section). -Peff
On Wed, Jul 21, 2021 at 05:58:41AM -0400, Jeff King wrote: > On Mon, Jun 21, 2021 at 06:25:07PM -0400, Taylor Blau wrote: > > > Even though the 'TECH_DOCS' variable was introduced all the way back in > > 5e00439f0a (Documentation: build html for all files in technical and > > howto, 2012-10-23), the 'bitmap-format' document was never added to that > > list when it was created. > > > > Prepare for changes to this file by including it in the list of > > technical documentation that 'make doc' will build by default. > > OK. I don't care that much about being able to format this as html, but > I agree it's good to be consistent with the other stuff in technical/. > > The big question is whether it looks OK rendered by asciidoc, and the > answer seems to be "yes" (from a cursory look I gave it). Actually, I take it back. After looking more carefully, it renders quite poorly. There's a lot of structural indentation that ends up being confused as code blocks. I don't know if it's better to have a poorly-formatted HTML file, or none at all. :) Personally, I would just read the source. And I have a slight concern that if we start "cleaning it up" to render as asciidoc, the source might end up a lot less readable (though I'd reserve judgement until actually seeing it). -Peff
On Wed, Jul 21, 2021 at 06:04:15AM -0400, Jeff King wrote: > The git-scm.com site doesn't use our Documentation/Makefile, so it has > been building the bitmap-format page for a while. It doesn't look > correct, though (it is missing everything before the "on-disk format" > section). Doh, nevermind. That nice header section does not exist before Taylor's series. ;) The git-scm.com page does seem to throw away the "GIT bitmap v1 format" title entirely. And it suffers the same rendering problems I saw when building with asciidoc locally. -Peff
On Wed, Jul 21, 2021 at 06:08:18AM -0400, Jeff King wrote: > On Wed, Jul 21, 2021 at 05:58:41AM -0400, Jeff King wrote: > > > On Mon, Jun 21, 2021 at 06:25:07PM -0400, Taylor Blau wrote: > > > > > Even though the 'TECH_DOCS' variable was introduced all the way back in > > > 5e00439f0a (Documentation: build html for all files in technical and > > > howto, 2012-10-23), the 'bitmap-format' document was never added to that > > > list when it was created. > > > > > > Prepare for changes to this file by including it in the list of > > > technical documentation that 'make doc' will build by default. > > > > OK. I don't care that much about being able to format this as html, but > > I agree it's good to be consistent with the other stuff in technical/. > > > > The big question is whether it looks OK rendered by asciidoc, and the > > answer seems to be "yes" (from a cursory look I gave it). > > Actually, I take it back. After looking more carefully, it renders quite > poorly. There's a lot of structural indentation that ends up being > confused as code blocks. > > I don't know if it's better to have a poorly-formatted HTML file, or > none at all. :) > > Personally, I would just read the source. And I have a slight concern > that if we start "cleaning it up" to render as asciidoc, the source > might end up a lot less readable (though I'd reserve judgement until > actually seeing it). Yeah, the actual source is pretty readable (and it's what I had been looking at, although it is sometimes convenient to have a version I can read in my web browser). But it's definitely not good Asciidoc. I briefly considered cleaning it up, but decided against it. Usually I would opt to clean it up, but this series is already so large that I figured it would make a negative impact on the reviewer experience to read a clean-up patch here. I wouldn't be opposed to coming back to it in the future, once the dust settles. I guess we can consider this #leftoverbits until then. Thanks, Taylor
On Wed, Jul 21, 2021 at 01:23:34PM -0400, Taylor Blau wrote: > > I don't know if it's better to have a poorly-formatted HTML file, or > > none at all. :) > > > > Personally, I would just read the source. And I have a slight concern > > that if we start "cleaning it up" to render as asciidoc, the source > > might end up a lot less readable (though I'd reserve judgement until > > actually seeing it). > > Yeah, the actual source is pretty readable (and it's what I had been > looking at, although it is sometimes convenient to have a version I can > read in my web browser). But it's definitely not good Asciidoc. > > I briefly considered cleaning it up, but decided against it. Usually I > would opt to clean it up, but this series is already so large that I > figured it would make a negative impact on the reviewer experience to > read a clean-up patch here. > > I wouldn't be opposed to coming back to it in the future, once the dust > settles. I guess we can consider this #leftoverbits until then. Yeah, I definitely don't want to see that cleanup as a dependency for this series. It's already long enough as it is. Coming back to it later is just fine with me. The question here is: should we continue to omit it from the html build, since it does not render well (i.e., should we simply drop this patch). -Peff
On Fri, Jul 23, 2021 at 03:39:25AM -0400, Jeff King wrote: > The question here is: should we continue to omit it from the html build, > since it does not render well (i.e., should we simply drop this patch). I think that's a nice way of putting it. Since the HTML rendering is terrible, let's just drop this patch and leave cleaning it up as #leftoverbits. Thanks, Taylor
diff --git a/Documentation/Makefile b/Documentation/Makefile index f5605b7767..7d7b778b28 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -90,6 +90,7 @@ SP_ARTICLES += $(API_DOCS) TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches +TECH_DOCS += technical/bitmap-format TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol TECH_DOCS += technical/index-format
Even though the 'TECH_DOCS' variable was introduced all the way back in 5e00439f0a (Documentation: build html for all files in technical and howto, 2012-10-23), the 'bitmap-format' document was never added to that list when it was created. Prepare for changes to this file by including it in the list of technical documentation that 'make doc' will build by default. Signed-off-by: Taylor Blau <me@ttaylorr.com> --- Documentation/Makefile | 1 + 1 file changed, 1 insertion(+)