threads / patch / 36683

patchDocumentation/technical/api-hashmap: Remove source highlighting

Subject: [PATCH] Documentation/technical/api-hashmap: Remove source highlighting

## tl;dr

6 messages between May 17, 2014 and May 20, 2014. Diffs are folded; open one to read it.

replies: 5people: 3as markdown or json

Anders Kaseorg· May 17, 2014, 11:08 UTC · lore

The highlighting was pretty, but unfortunately, the failure mode when source-highlight is not installed was that the entire code block disappears. See https://bugs.debian.org/745591, https://bugs.launchpad.net/bugs/1316810.

Signed-off-by: Anders Kaseorg <andersk@mit.edu>
---
 Documentation/technical/api-hashmap.txt | 1 -
 1 file changed, 1 deletion(-)

Show changes to Documentation/technical/api-hashmap.txt +0 −1

diff --git a/Documentation/technical/api-hashmap.txt b/Documentation/technical/api-hashmap.txt
index 42ca234..b977ae8 100644
--- a/Documentation/technical/api-hashmap.txt
+++ b/Documentation/technical/api-hashmap.txt
@@ -166,7 +166,6 @@ Usage example
 -------------
 
 Here's a simple usage example that maps long keys to double values.
-[source,c]
 ------------
 struct hashmap map;

-- 
2.0.0.rc3

Jeremiah Mahler· May 17, 2014, 15:22 UTC · re: Anders Kaseorg · lore

Re: [PATCH] Documentation/technical/api-hashmap: Remove source highlighting

On Sat, May 17, 2014 at 07:08:55AM -0400, Anders Kaseorg wrote:

Show 5 quoted lines

> The highlighting was pretty, but unfortunately, the failure mode when
> source-highlight is not installed was that the entire code block
> disappears.  See https://bugs.debian.org/745591,
> https://bugs.launchpad.net/bugs/1316810.
>

I agree that a broken document is an unacceptable failure mode.

But I do not understand why 'source-highlight' is not an install requirement for 'git-doc'. If I install 'source-highlight' on my Debian machine the code looks great.

  apt-get install source-highlight

I also noticed that this seems to be the single place where source code highlighting is used in Documentation/technical. So it might be worthwhile to eliminate this dependency all together as Anders patch does.

-- 
Jeremiah Mahler
jmmahler@gmail.com
http://github.com/jmahler

Anders Kaseorg· May 18, 2014, 00:50 UTC · re: Jeremiah Mahler · lore

Re: [PATCH] Documentation/technical/api-hashmap: Remove source highlighting

On Sat, 17 May 2014, Jeremiah Mahler wrote:

Show 7 quoted lines

> I agree that a broken document is an unacceptable failure mode.
> 
> But I do not understand why 'source-highlight' is not an install
> requirement for 'git-doc'.  If I install 'source-highlight' on
> my Debian machine the code looks great.
> 
>   apt-get install source-highlight

Yes; when I noticed this failure, I asked Jonathan to add source-highlight as a build dependency in Debian (https://bugs.debian.org/745591). But then Ubuntu forked the packaging to revert this change (https://bugs.launchpad.net/bugs/1316810), because source-highlight in the community-supported universe repository is not allowed to be a build dependency of git in the Canonical-supported main repository. So now the Ubuntu package still has broken documentation _and_ it’s lost the ability to automatically synchronize updates from Debian.

If we’re going to make Git depend on source-highlight, then we would want to make sure it’s documented in INSTALL and that its absence is properly diagnosed. Maybe then we could make the argument to Canonical that source-highlight should become officially supported in main (https://wiki.ubuntu.com/UbuntuMainInclusionRequirements).

But I don’t that would be worth it just to make one page of the API documentation a little more colorful (and it sounds like you agree).

Anders

Junio C Hamano· May 19, 2014, 17:09 UTC · re: Anders Kaseorg · lore

Re: [PATCH] Documentation/technical/api-hashmap: Remove source highlighting

Anders Kaseorg <andersk@MIT.EDU> writes:

Show 6 quoted lines

> Yes; when I noticed this failure, I asked Jonathan to add source-highlight 
> as a build dependency in Debian (https://bugs.debian.org/745591).  But 
> then Ubuntu forked the packaging to revert this change 
> (https://bugs.launchpad.net/bugs/1316810), because source-highlight in the 
> community-supported universe repository is not allowed to be a build 
> dependency ...

The reasoning and solution Ubuntu has sounds sensible *but* it also soudns like it is incomplete. If Ubuntu does not want to use highlight, it can apply a change like the patch in question as part of their fork to make the end result consistent and they are failing to do so. If the tooling do not use highlight, the source should not require highlight, either. It is ultimately their bug.

It however *is* our business, as their upstream, to make it easier for distros that want to use and distros that do not want to depend on highlight, and aiming for a solution that relieves Ubuntu or any other distros from needing to carry one more patch is a good thing.

How bad does the documentation look with the patch applied (I know how bad it looks without source-highlight installed)? If it is not too bad, then it sounds like a sensible solution to drop the highlight markup unconditionally like the patch that started this thread does, taking the "common denominator" approach. You seem to agree, and I do not object, either.

> But I don’t that would be worth it just to make one page of the API 
> documentation a little more colorful (and it sounds like you agree).

Anders Kaseorg· May 19, 2014, 23:40 UTC · re: Junio C Hamano · lore

Re: [PATCH] Documentation/technical/api-hashmap: Remove source highlighting

On Mon, 19 May 2014, Junio C Hamano wrote:

> If Ubuntu does not want to use highlight, it can apply a change like the 
> patch in question as part of their fork to make the end result 
> consistent and they are failing to do so.

Sure, Ubuntu can apply that patch, but the larger problem remains: if the Ubuntu packaging is even slightly different from Debian’s, it is no longer eligible for automatic synchronization from Debian.

When that has happened in the past, the result was that the Ubuntu version languished far behind the Debian version, because Canonical doesn’t have the manpower to manually merge every Debian update. Ubuntu 9.04 shipped with Git 1.6.0.4 instead of 1.6.2.4 because they had failed to update their packaging after patching out a dependency on cvsps.

If this Ubuntu nonsense were obstructing something important upstream, then of course I would be yelling at Ubuntu to get their act together; in that case, I filed a main inclusion report to get Canonical to officially support cvsps (https://bugs.launchpad.net/bugs/369111) so Ubuntu could drop their patch. But here we’re talking about syntax highlighting in one page of internal documentation that basically nobody is going to read, and that argument wouldn’t carry any weight.

We could put the patch into Debian instead of Ubuntu to eliminate the Ubuntu delta; Jonathan has been friendly enough to Ubuntu that I think he would grudgingly agree. But I’m submitting it upstream because other distros will eventually run into the same problem: there’s no obvious cue that source-highlight needs to be added as a new dependency besides a warning message buried in the middle of the build log.

Show 6 quoted lines

> How bad does the documentation look with the patch applied (I know how 
> bad it looks without source-highlight installed)?  If it is not too bad, 
> then it sounds like a sensible solution to drop the highlight markup 
> unconditionally like the patch that started this thread does, taking the 
> "common denominator" approach.  You seem to agree, and I do not object, 
> either.

Original version with syntax-highlight installed (pretty): http://web.mit.edu/andersk/Public/api-hashmap/old-highlight.html

Original version with syntax-highlight missing (corrupted): http://web.mit.edu/andersk/Public/api-hashmap/old-no-highlight.html

Patched version (boring but readable): http://web.mit.edu/andersk/Public/api-hashmap/patched.html

Anders

Junio C Hamano· May 20, 2014, 17:31 UTC · re: Anders Kaseorg · lore

Re: [PATCH] Documentation/technical/api-hashmap: Remove source highlighting

Anders Kaseorg <andersk@MIT.EDU> writes:

Show 15 quoted lines

>> How bad does the documentation look with the patch applied (I know how 
>> bad it looks without source-highlight installed)?  If it is not too bad, 
>> then it sounds like a sensible solution to drop the highlight markup 
>> unconditionally like the patch that started this thread does, taking the 
>> "common denominator" approach.  You seem to agree, and I do not object, 
>> either.
>
> Original version with syntax-highlight installed (pretty):
> http://web.mit.edu/andersk/Public/api-hashmap/old-highlight.html
>
> Original version with syntax-highlight missing (corrupted):
> http://web.mit.edu/andersk/Public/api-hashmap/old-no-highlight.html
>
> Patched version (boring but readable):
> http://web.mit.edu/andersk/Public/api-hashmap/patched.html

Thanks. I've queued the patch for v2.0 and the comparison between the first and the third clearly shows that it is the right thing to do ;-).