Re: [RFC/PATCH] Formatting variables in the documentation
Jeff King writes: > On Thu, May 26, 2016 at 09:18:17AM -0700, Junio C Hamano wrote: > >> > 1. Somebody produces a patch flipping the default. The patch is >> > trivial, but the commit message should tell why, and try to dig up >> > any possible problems we might see (e.g., why wasn't this the >> > default? Particular versions of tools? Some platforms?) >> [...] >> There was no particular "caveat" raised there to recommend against >> using this on particular versions of tools or platforms. It was >> inertia that has kept the new optional feature "optional". > > Thanks for digging. That matches my recollection and the limited > research I did more recently. For completeness's sake I should point out that the discussion on the first thread did point out some version-dependent issues. But with 79c461d5 (docs: default to more modern toolset, 2010-11-19), we declared the problematic versions obsolete; I suspect that it is safe to assume that those who would be hurt by flipping the default would already be extinct after 6 years since then. >> > 2. Assuming no problems, Junio merges the patch to "next". We get >> > any reports of issues from people using "next" day-to-day. >> >> So I can do these steps myself up to this point. After waiting for >> a few days to see if somebody else with better memory tells me what >> I forgot, perhaps. > > OK. I was trying to see if (1) could be low-hanging fruit for any of the > newcomers, but at this point it probably makes sense for you to just > write the patch. Leaving it as low-hanging fruit is actually a good idea. I was thinking about flipping it in Meta/dodoc.sh, which would update the git-manpages.git repository whose mirrors are found at git://git.kernel.org/pub/scm/git/git-manpages.git/ git://repo.or.cz/git-manpages.git/ git://github.com/gitster/git-manpages.git/ -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC/PATCH] Formatting variables in the documentation
On Thu, May 26, 2016 at 09:37:19AM -0700, Junio C Hamano wrote: > >> There was no particular "caveat" raised there to recommend against > >> using this on particular versions of tools or platforms. It was > >> inertia that has kept the new optional feature "optional". > > > > Thanks for digging. That matches my recollection and the limited > > research I did more recently. > > For completeness's sake I should point out that the discussion on > the first thread did point out some version-dependent issues. But > with 79c461d5 (docs: default to more modern toolset, 2010-11-19), we > declared the problematic versions obsolete; I suspect that it is > safe to assume that those who would be hurt by flipping the default > would already be extinct after 6 years since then. Yeah, I'd agree, though that may be worth mentioning in the commit message. > > OK. I was trying to see if (1) could be low-hanging fruit for any of the > > newcomers, but at this point it probably makes sense for you to just > > write the patch. > > Leaving it as low-hanging fruit is actually a good idea. > > I was thinking about flipping it in Meta/dodoc.sh, which would > update the git-manpages.git repository whose mirrors are found at Ah, right. I was thinking that the patch would go to "master" first, but there is no reason it could not be flipped independently for your build process. -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC/PATCH] Formatting variables in the documentation
On Thu, May 26, 2016 at 09:18:17AM -0700, Junio C Hamano wrote: > > 1. Somebody produces a patch flipping the default. The patch is > > trivial, but the commit message should tell why, and try to dig up > > any possible problems we might see (e.g., why wasn't this the > > default? Particular versions of tools? Some platforms?) > [...] > There was no particular "caveat" raised there to recommend against > using this on particular versions of tools or platforms. It was > inertia that has kept the new optional feature "optional". Thanks for digging. That matches my recollection and the limited research I did more recently. > > 2. Assuming no problems, Junio merges the patch to "next". We get > > any reports of issues from people using "next" day-to-day. > > So I can do these steps myself up to this point. After waiting for > a few days to see if somebody else with better memory tells me what > I forgot, perhaps. OK. I was trying to see if (1) could be low-hanging fruit for any of the newcomers, but at this point it probably makes sense for you to just write the patch. -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC/PATCH] Formatting variables in the documentation
Jeff King writes: > On Mon, May 23, 2016 at 07:57:43PM +0200, Matthieu Moy wrote: > >> Samuel GROOT writes: >> >> > Since 2.8.3 was out recently, we could flip MAN_BOLD_LITERAL on by >> > default for this cycle to shake out problems as Jeff King suggested >> > [2]. >> >> 2.8.3 was a bufix release, and flipping a controversial flag should >> clearly not be done on a bugfix release. So, in this context, "beginning >> of a cycle" means after a x.y.0 release. >> >> Anyway, a patch enabling MAN_BOLD_LITERAL by default would need to cook >> in pu and next as any other patches, so the time when the patch is sent >> does not really matter. > > Yeah, I think a reasonable plan is: > > 1. Somebody produces a patch flipping the default. The patch is > trivial, but the commit message should tell why, and try to dig up > any possible problems we might see (e.g., why wasn't this the > default? Particular versions of tools? Some platforms?) "git log -SBOLD_LITERAL Documentation/" tells me that it's not like we had this on by default sometime in the past and then we flipped the default back in response to some problems (which I forgot about). I just re-read the two iterations that introduced BOLD_LITERAL: * http://news.gmane.org/find-root.php?message_id=<1237881866-5497-1-git-send-email-chris_john...@pobox.com> * http://news.gmane.org/find-root.php?message_id=<1238136245-22853-1-git-send-email-chris_john...@pobox.com> There was no particular "caveat" raised there to recommend against using this on particular versions of tools or platforms. It was inertia that has kept the new optional feature "optional". > 2. Assuming no problems, Junio merges the patch to "next". We get > any reports of issues from people using "next" day-to-day. So I can do these steps myself up to this point. After waiting for a few days to see if somebody else with better memory tells me what I forgot, perhaps. > 3. Assuming no problems, Junio merges to "master". We hit more people > (who build from master). And also it would be part of the > pre-generated pages that Junio ships, so we might get reports > there. > > 4. Eventually it's released. We hope to get no problem reports there, > though it _does_ hit a wider audience at that point. > > Steps 1 and 2 can happen now. As we are in the -rc cycle right now, > probably step 3 would happen post-v2.9. But there's no reason not to > start the clock ticking now. > > -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC/PATCH] Formatting variables in the documentation
On Mon, May 23, 2016 at 07:57:43PM +0200, Matthieu Moy wrote: > Samuel GROOT writes: > > > Since 2.8.3 was out recently, we could flip MAN_BOLD_LITERAL on by > > default for this cycle to shake out problems as Jeff King suggested > > [2]. > > 2.8.3 was a bufix release, and flipping a controversial flag should > clearly not be done on a bugfix release. So, in this context, "beginning > of a cycle" means after a x.y.0 release. > > Anyway, a patch enabling MAN_BOLD_LITERAL by default would need to cook > in pu and next as any other patches, so the time when the patch is sent > does not really matter. Yeah, I think a reasonable plan is: 1. Somebody produces a patch flipping the default. The patch is trivial, but the commit message should tell why, and try to dig up any possible problems we might see (e.g., why wasn't this the default? Particular versions of tools? Some platforms?) 2. Assuming no problems, Junio merges the patch to "next". We get any reports of issues from people using "next" day-to-day. 3. Assuming no problems, Junio merges to "master". We hit more people (who build from master). And also it would be part of the pre-generated pages that Junio ships, so we might get reports there. 4. Eventually it's released. We hope to get no problem reports there, though it _does_ hit a wider audience at that point. Steps 1 and 2 can happen now. As we are in the -rc cycle right now, probably step 3 would happen post-v2.9. But there's no reason not to start the clock ticking now. -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC/PATCH] Formatting variables in the documentation
Samuel GROOT writes: > Since 2.8.3 was out recently, we could flip MAN_BOLD_LITERAL on by > default for this cycle to shake out problems as Jeff King suggested > [2]. 2.8.3 was a bufix release, and flipping a controversial flag should clearly not be done on a bugfix release. So, in this context, "beginning of a cycle" means after a x.y.0 release. Anyway, a patch enabling MAN_BOLD_LITERAL by default would need to cook in pu and next as any other patches, so the time when the patch is sent does not really matter. -- Matthieu Moy http://www-verimag.imag.fr/~moy/ -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC/PATCH] Formatting variables in the documentation
Some people have suggested to standardize documentation's formatting to make it more consistent. [1] 2015-04-29 20:13:53 GMT, Junio C Hamano wrote: Interesting. What I happen to use when populating the git-manpages repository would have wider impact to the users, as I hear that some (or many) distros just package whatever I have there. I do not mind enabling it on my end if that gives us more readable rendition. [2] On 2015-04-29 20:32:47, Jeff King wrote: I think it's probably fine and a positive change, but one never knows. I guess distros don't package what you ship until you actually tag a release, so it would be OK to start doing so during a cycle to shake out any problems (and in fact preferable, as anybody who follows "master" using "make install-man-quick" would get it early and be able to make a report). If we are doing that, it would make sense to flip MAN_BOLD_LITERAL on by default during that same cycle, so we could get reports from people who build the manpages from source. [3] On 2015-11-13 05:45:05, Jeff King wrote: If we want to move to backticks, we probably want to also turn on MAN_BOLD_LITERAL by default, or it's a step backwards for some folks. The question is about flipping MAN_BOLD_LITERAL by default or not. Since 2.8.3 was out recently, we could flip MAN_BOLD_LITERAL on by default for this cycle to shake out problems as Jeff King suggested [2]. Another option could be testing if the system does support bold literal and flipping it on or off accordingly, but I don't know exactly where that could be done. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC/PATCH] Formatting variables in the documentation
On Wed, May 18, 2016 at 05:58:29PM +0200, Tom Russello wrote: > There is no agreement on this topic (the CodingGuidelines does not > mention it), it would be better if everyone follows the same rule: put > each environment variable in monospace style and write this rule in > the guide. > > It is a good thing to have a consistent documentation however it > will be painful to change with a simple regex all occurences > (especially environment variables without any format) because some of > them are in paths or code section. > > What do you think ? Personally, I like the "literal" backticks versus the "emphasis" single-quotes. But you should keep in mind how they are rendered in the manpages, which is as "nothing" and "underline", respectively (by default, anyway). So I think some people are negative on using backticks for that reason. I also turn on the MAN_BOLD_LITERAL knob, which turns that "nothing" into "bold", and the result looks quite nice. But there is some compatibility question of whether that can be used everywhere. Here's the most recent discussion I could find: http://thread.gmane.org/gmane.comp.version-control.git/281170 which talks about the issue and references an earlier discussion (which I didn't re-read). But you probably need to address the concerns there before moving forward with a patch like this. -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
