{"thread":{"id":"34324","subject":"[PATCH] gitweb: allow extra breadcrumbs to prefix the trail","startedAt":"2013-07-02T15:49:08Z","lastAt":"2013-07-07T01:05:50Z","messageCount":15,"participants":["Tony Finch","Jonathan Nieder","Jakub Narębski"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"222372","messageId":"E1Uu3IT-0008U1-3c@hermes-2.csi.cam.ac.uk","threadId":"34324","inReplyTo":null,"subject":"[PATCH] gitweb: allow extra breadcrumbs to prefix the trail","fromName":"Tony Finch","fromEmail":"dot@dotat.at","sentAt":"2013-07-02T15:49:08Z","receivedAt":"2013-07-02T15:49:08Z","isPatch":true,"sender":{"key":"dot@dotat.at","avatar":"https://avatars.githubusercontent.com/u/68429?v=4"},"body":"There are often parent pages logically above the gitweb projects\nlist, e.g. home pages of the organization and department that host\nthe gitweb server. This change allows you to include links to those\npages in gitweb's breadcrumb trail.\n\nSigned-off-by: Tony Finch <dot@dotat.at>\n---\n Documentation/gitweb.conf.txt | 8 ++++++++\n gitweb/gitweb.perl            | 6 ++++++\n 2 files changed, 14 insertions(+)\n\ndiff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt\nindex ea0526e..4579578 100644\n--- a/Documentation/gitweb.conf.txt\n+++ b/Documentation/gitweb.conf.txt\n@@ -339,6 +339,14 @@ $home_link_str::\n \tas this link leads to the list of projects.  Other popular choice it to\n \tset it to the name of site.\n \n+@extra_breadcrumbs::\n+\tAdditional links to be added to the start of the breadcrumb trail,\n+\tthat are logically \"above\" the gitweb projects list. For example,\n+\tlinks to the organization and department which host the gitweb\n+\tserver. Each element of the list is a reference to an array,\n+\tin which element 0 is the link text and element 1 is the\n+\ttarget URL.\n+\n $logo_url::\n $logo_label::\n \tURI and label (title) for the Git logo link (or your site logo,\ndiff --git a/gitweb/gitweb.perl b/gitweb/gitweb.perl\nindex 8d69ada..436f17a 100755\n--- a/gitweb/gitweb.perl\n+++ b/gitweb/gitweb.perl\n@@ -85,6 +85,9 @@ our $project_maxdepth = \"++GITWEB_PROJECT_MAXDEPTH++\";\n # string of the home link on top of all pages\n our $home_link_str = \"++GITWEB_HOME_LINK_STR++\";\n \n+# extra breadcrumbs preceding the home link\n+our @extra_breadcrumbs = ();\n+\n # name of your site or organization to appear in page titles\n # replace this with something more descriptive for clearer bookmarks\n our $site_name = \"++GITWEB_SITENAME++\"\n@@ -3982,6 +3985,9 @@ sub print_nav_breadcrumbs_path {\n sub print_nav_breadcrumbs {\n \tmy %opts = @_;\n \n+\tfor my $crumb (@extra_breadcrumbs) {\n+\t\tprint $cgi->a({-href => esc_url($crumb->[1])}, $crumb->[0]) . \" / \";\n+\t}\n \tprint $cgi->a({-href => esc_url($home_link)}, $home_link_str) . \" / \";\n \tif (defined $project) {\n \t\tmy @dirname = split '/', $project;\n-- \n1.8.3.1.605.g85318f5\n"},{"id":"222537","messageId":"E1UugA8-00054D-DL@hermes-2.csi.cam.ac.uk","threadId":"34324","inReplyTo":"E1Uu3IT-0008U1-3c@hermes-2.csi.cam.ac.uk","subject":"[PATCH v2] gitweb: allow extra breadcrumbs to prefix the trail","fromName":"Tony Finch","fromEmail":"dot@dotat.at","sentAt":"2013-07-02T15:49:08Z","receivedAt":"2013-07-02T15:49:08Z","isPatch":true,"sender":{"key":"dot@dotat.at","avatar":"https://avatars.githubusercontent.com/u/68429?v=4"},"body":"There are often parent pages logically above the gitweb projects\nlist, e.g. home pages of the organization and department that host\nthe gitweb server. This change allows you to include links to those\npages in gitweb's breadcrumb trail.\n\nSigned-off-by: Tony Finch <dot@dotat.at>\nReviewed-by: Jonathan Nieder <jrnieder@gmail.com>\n---\n\nThis update includes the documentation improvements suggested by\nJonathan Nieder and Jakub Narębski.\n\n Documentation/gitweb.conf.txt | 22 ++++++++++++++++++++--\n gitweb/gitweb.perl            |  6 ++++++\n 2 files changed, 26 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt\nindex ea0526e..305db63 100644\n--- a/Documentation/gitweb.conf.txt\n+++ b/Documentation/gitweb.conf.txt\n@@ -336,8 +336,26 @@ $home_link_str::\n \tused as the first component of gitweb's \"breadcrumb trail\":\n \t`<home link> / <project> / <action>`.  Can be set at build time using\n \tthe `GITWEB_HOME_LINK_STR` variable.  By default it is set to \"projects\",\n-\tas this link leads to the list of projects.  Other popular choice it to\n-\tset it to the name of site.\n+\tas this link leads to the list of projects.  Another popular choice is to\n+\tset it to the name of site.  Note that it is treated as raw HTML so it\n+\tshould not be set from untrusted sources.\n+\n+@extra_breadcrumbs::\n+\tAdditional links to be added to the start of the breadcrumb trail before\n+\tthe home link, to pages that are logically \"above\" the gitweb projects\n+\tlist, such as the organization and department which host the gitweb\n+\tserver. Each element of the list is a reference to an array, in which\n+\telement 0 is the link text (equivalent to `$home_link_str`) and element\n+\t1 is the target URL (equivalent to `$home_link`).\n++\n+For example, the following setting produces a breadcrumb trail like\n+\"home / dev / projects / ...\" where \"projects\" is the home link.\n+----------------------------------------------------------------------------\n+    our @extra_breadcrumbs = (\n+      [ 'home' => 'https://www.example.org/' ],\n+      [ 'dev'  => 'https://dev.example.org/' ],\n+    );\n+----------------------------------------------------------------------------\n \n $logo_url::\n $logo_label::\ndiff --git a/gitweb/gitweb.perl b/gitweb/gitweb.perl\nindex 8d69ada..436f17a 100755\n--- a/gitweb/gitweb.perl\n+++ b/gitweb/gitweb.perl\n@@ -85,6 +85,9 @@ our $project_maxdepth = \"++GITWEB_PROJECT_MAXDEPTH++\";\n # string of the home link on top of all pages\n our $home_link_str = \"++GITWEB_HOME_LINK_STR++\";\n \n+# extra breadcrumbs preceding the home link\n+our @extra_breadcrumbs = ();\n+\n # name of your site or organization to appear in page titles\n # replace this with something more descriptive for clearer bookmarks\n our $site_name = \"++GITWEB_SITENAME++\"\n@@ -3982,6 +3985,9 @@ sub print_nav_breadcrumbs_path {\n sub print_nav_breadcrumbs {\n \tmy %opts = @_;\n \n+\tfor my $crumb (@extra_breadcrumbs) {\n+\t\tprint $cgi->a({-href => esc_url($crumb->[1])}, $crumb->[0]) . \" / \";\n+\t}\n \tprint $cgi->a({-href => esc_url($home_link)}, $home_link_str) . \" / \";\n \tif (defined $project) {\n \t\tmy @dirname = split '/', $project;\n-- \n1.8.3.1.605.g85318f5\n"},{"id":"222510","messageId":"20130703215930.GT408@google.com","threadId":"34324","inReplyTo":"E1Uu3IT-0008U1-3c@hermes-2.csi.cam.ac.uk","subject":"Re: [PATCH] gitweb: allow extra breadcrumbs to prefix the trail","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-07-03T21:59:30Z","receivedAt":"2013-07-03T21:59:30Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"(cc-ing Jakub, gitweb wrangler)\n\nTony Finch wrote:\n\n> There are often parent pages logically above the gitweb projects\n> list, e.g. home pages of the organization and department that host\n> the gitweb server. This change allows you to include links to those\n> pages in gitweb's breadcrumb trail.\n\nNeat.\n\n> Signed-off-by: Tony Finch <dot@dotat.at>\n> ---\n>  Documentation/gitweb.conf.txt | 8 ++++++++\n>  gitweb/gitweb.perl            | 6 ++++++\n>  2 files changed, 14 insertions(+)\n> \n> diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt\n> index ea0526e..4579578 100644\n> --- a/Documentation/gitweb.conf.txt\n> +++ b/Documentation/gitweb.conf.txt\n> @@ -339,6 +339,14 @@ $home_link_str::\n>  \tas this link leads to the list of projects.  Other popular choice it to\n>  \tset it to the name of site.\n>  \n> +@extra_breadcrumbs::\n> +\tAdditional links to be added to the start of the breadcrumb trail,\n> +\tthat are logically \"above\" the gitweb projects list. For example,\n> +\tlinks to the organization and department which host the gitweb\n> +\tserver. Each element of the list is a reference to an array,\n> +\tin which element 0 is the link text and element 1 is the\n> +\ttarget URL.\n\nIs arbitrary HTML permitted in the link text?\n\nI think it makes sense to permit it for consistency with $home_link_str,\nbut it might be worth mentioning in the manpage so the administrator\nknows not to set it to something user-controlled --- e.g.:\n\n\tThe link text can contain arbitrary HTML --- to escape link\n\ttext generated programatically, use esc_html($text).\n\nFor what it's worth, with or without such a change,\nReviewed-by: Jonathan Nieder <jrnieder@gmail.com>\n\n(Patch left unsnipped for reference.)\n> +\n>  $logo_url::\n>  $logo_label::\n>  \tURI and label (title) for the Git logo link (or your site logo,\n> diff --git a/gitweb/gitweb.perl b/gitweb/gitweb.perl\n> index 8d69ada..436f17a 100755\n> --- a/gitweb/gitweb.perl\n> +++ b/gitweb/gitweb.perl\n> @@ -85,6 +85,9 @@ our $project_maxdepth = \"++GITWEB_PROJECT_MAXDEPTH++\";\n>  # string of the home link on top of all pages\n>  our $home_link_str = \"++GITWEB_HOME_LINK_STR++\";\n>  \n> +# extra breadcrumbs preceding the home link\n> +our @extra_breadcrumbs = ();\n> +\n>  # name of your site or organization to appear in page titles\n>  # replace this with something more descriptive for clearer bookmarks\n>  our $site_name = \"++GITWEB_SITENAME++\"\n> @@ -3982,6 +3985,9 @@ sub print_nav_breadcrumbs_path {\n>  sub print_nav_breadcrumbs {\n>  \tmy %opts = @_;\n>  \n> +\tfor my $crumb (@extra_breadcrumbs) {\n> +\t\tprint $cgi->a({-href => esc_url($crumb->[1])}, $crumb->[0]) . \" / \";\n> +\t}\n>  \tprint $cgi->a({-href => esc_url($home_link)}, $home_link_str) . \" / \";\n>  \tif (defined $project) {\n>  \t\tmy @dirname = split '/', $project;\n> -- \n"},{"id":"222511","messageId":"CANQwDwcneUzzXS-Du-3Aca3-Vp8ycSzVqUv1rVRVhaNUWfeokw@mail.gmail.com","threadId":"34324","inReplyTo":"20130703215930.GT408@google.com","subject":"Re: [PATCH] gitweb: allow extra breadcrumbs to prefix the trail","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2013-07-03T22:11:01Z","receivedAt":"2013-07-03T22:11:01Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"On Wed, Jul 3, 2013 at 11:59 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:\n> Tony Finch wrote:\n\n>> +@extra_breadcrumbs::\n>> +     Additional links to be added to the start of the breadcrumb trail,\n>> +     that are logically \"above\" the gitweb projects list. For example,\n>> +     links to the organization and department which host the gitweb\n>> +     server. Each element of the list is a reference to an array,\n>> +     in which element 0 is the link text and element 1 is the\n>> +     target URL.\n>\n> Is arbitrary HTML permitted in the link text?\n>\n> I think it makes sense to permit it for consistency with $home_link_str,\n> but it might be worth mentioning in the manpage so the administrator\n> knows not to set it to something user-controlled --- e.g.:\n>\n>         The link text can contain arbitrary HTML --- to escape link\n>         text generated programatically, use esc_html($text).\n\nNb. it would be nice to have relation of @extra_breadcrumbs with\n$home_link_str explained.\n\n-- \nJakub Narebski\n"},{"id":"222534","messageId":"alpine.LSU.2.00.1307040940400.26246@hermes-2.csi.cam.ac.uk","threadId":"34324","inReplyTo":"CANQwDwcneUzzXS-Du-3Aca3-Vp8ycSzVqUv1rVRVhaNUWfeokw@mail.gmail.com","subject":"Re: [PATCH] gitweb: allow extra breadcrumbs to prefix the trail","fromName":"Tony Finch","fromEmail":"dot@dotat.at","sentAt":"2013-07-04T08:44:50Z","receivedAt":"2013-07-04T08:44:50Z","isPatch":true,"sender":{"key":"dot@dotat.at","avatar":"https://avatars.githubusercontent.com/u/68429?v=4"},"body":"Jakub Narębski <jnareb@gmail.com> wrote:\n> On Wed, Jul 3, 2013 at 11:59 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:\n> > Tony Finch wrote:\n>\n> >> +@extra_breadcrumbs::\n> >> +     Additional links to be added to the start of the breadcrumb trail,\n> >> +     that are logically \"above\" the gitweb projects list. For example,\n> >> +     links to the organization and department which host the gitweb\n> >> +     server. Each element of the list is a reference to an array,\n> >> +     in which element 0 is the link text and element 1 is the\n> >> +     target URL.\n> >\n> > Is arbitrary HTML permitted in the link text?\n\nI had the same question when I was wondering about abusing $home_link_str\nto do this without a patch :-)\n\n> > I think it makes sense to permit it for consistency with $home_link_str,\n> > but it might be worth mentioning in the manpage so the administrator\n> > knows not to set it to something user-controlled --- e.g.:\n\nI left this detail out of the man page for consistency with the\ndocumentation for $home_link_str.\n\n> Nb. it would be nice to have relation of @extra_breadcrumbs with\n> $home_link_str explained.\n\nI will make that clearer.\n\nThanks for reviewing the patch.\n\nTony.\n-- \nf.anthony.n.finch  <dot@dotat.at>  http://dotat.at/\nForties, Cromarty: East, veering southeast, 4 or 5, occasionally 6 at first.\nRough, becoming slight or moderate. Showers, rain at first. Moderate or good,\noccasionally poor at first."},{"id":"222563","messageId":"CANQwDwd9siyeu5xqS5Un+=8ioEaDbpT30vBpgJCVNUEcszcv1g@mail.gmail.com","threadId":"34324","inReplyTo":"alpine.LSU.2.00.1307040940400.26246@hermes-2.csi.cam.ac.uk","subject":"Re: [PATCH] gitweb: allow extra breadcrumbs to prefix the trail","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2013-07-04T14:40:51Z","receivedAt":"2013-07-04T14:40:51Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"On Thu, Jul 4, 2013 at 10:44 AM, Tony Finch <dot@dotat.at> wrote:\n> Jakub Narębski <jnareb@gmail.com> wrote:\n>> On Wed, Jul 3, 2013 at 11:59 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:\n>>> Tony Finch wrote:\n>>\n>>>> +@extra_breadcrumbs::\n\nBTW. perhaps (it is only an idea) @top_level_breadcrumbs or\n@home_breadcrumbs would be a better name for this variable.\n\n>>>> +     Additional links to be added to the start of the breadcrumb trail,\n>>>> +     that are logically \"above\" the gitweb projects list. For example,\n>>>> +     links to the organization and department which host the gitweb\n>>>> +     server. Each element of the list is a reference to an array,\n>>>> +     in which element 0 is the link text and element 1 is the\n>>>> +     target URL.\n>>>\n>>> Is arbitrary HTML permitted in the link text?\n>\n> I had the same question when I was wondering about abusing $home_link_str\n> to do this without a patch :-)\n\nNot exactly arbitrary, as it is inside A element, so it cannot contain A links\nitself (hyperlinks should not be nested), but it is not esc_html-aped.\n\n>\n>>> I think it makes sense to permit it for consistency with $home_link_str,\n>>> but it might be worth mentioning in the manpage so the administrator\n>>> knows not to set it to something user-controlled --- e.g.:\n>\n> I left this detail out of the man page for consistency with the\n> documentation for $home_link_str.\n\nIt would be better to improve documentation, than follow current bad\npractice... ;-P\n\n>> Nb. it would be nice to have relation of @extra_breadcrumbs with\n>> $home_link_str explained.\n>\n> I will make that clearer.\n\nPerhaps even make ( [ $home_link_str, $home_link ] ) to be default\nvalue for @extra_breadcrumbs, making new feature generalization\nof $home_link*, similarly to how it was done for $stylesheet -> @stylesheets\ntransition.\n\nWhat do you think about it?\n-- \nJakub Narębski\n"},{"id":"222564","messageId":"alpine.LSU.2.00.1307041559140.26246@hermes-2.csi.cam.ac.uk","threadId":"34324","inReplyTo":"CANQwDwd9siyeu5xqS5Un+=8ioEaDbpT30vBpgJCVNUEcszcv1g@mail.gmail.com","subject":"Re: [PATCH] gitweb: allow extra breadcrumbs to prefix the trail","fromName":"Tony Finch","fromEmail":"dot@dotat.at","sentAt":"2013-07-04T15:11:15Z","receivedAt":"2013-07-04T15:11:15Z","isPatch":true,"sender":{"key":"dot@dotat.at","avatar":"https://avatars.githubusercontent.com/u/68429?v=4"},"body":"Jakub Narębski <jnareb@gmail.com> wrote:\n>\n> It would be better to improve documentation, than follow current bad\n> practice... ;-P\n\nThe v2 patch does just that :-)\n\n> Perhaps even make ( [ $home_link_str, $home_link ] ) to be default\n> value for @extra_breadcrumbs, making new feature generalization\n> of $home_link*, similarly to how it was done for $stylesheet -> @stylesheets\n> transition.\n\nI don't think that's a win. There's a lot of existing gitweb.conf out\nthere which sets $home_link_str, so the code would have to either print\nthe last element of @extra_breadcrumbs or the $home_link variables\ndepending on whether the variables were modified. And the documentation\nwould have to explain this complicated arrangement.\n\nTony.\n-- \nf.anthony.n.finch  <dot@dotat.at>  http://dotat.at/\nForties, Cromarty: East, veering southeast, 4 or 5, occasionally 6 at first.\nRough, becoming slight or moderate. Showers, rain at first. Moderate or good,\noccasionally poor at first."},{"id":"222565","messageId":"CANQwDwfCYPBjGfmKOLju-Zey4WrVrXfaymJtu9g1OYvOUfBTcw@mail.gmail.com","threadId":"34324","inReplyTo":"alpine.LSU.2.00.1307041559140.26246@hermes-2.csi.cam.ac.uk","subject":"Re: [PATCH] gitweb: allow extra breadcrumbs to prefix the trail","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2013-07-04T15:34:58Z","receivedAt":"2013-07-04T15:34:58Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"On Thu, Jul 4, 2013 at 5:11 PM, Tony Finch <dot@dotat.at> wrote:\n> Jakub Narębski <jnareb@gmail.com> wrote:\n>>\n>> It would be better to improve documentation, than follow current bad\n>> practice... ;-P\n>\n> The v2 patch does just that :-)\n\nThanks.\n\n>> Perhaps even make ( [ $home_link_str, $home_link ] ) to be default\n>> value for @extra_breadcrumbs, making new feature generalization\n>> of $home_link*, similarly to how it was done for $stylesheet -> @stylesheets\n>> transition.\n>\n> I don't think that's a win. There's a lot of existing gitweb.conf out\n> there which sets $home_link_str, so the code would have to either print\n> the last element of @extra_breadcrumbs or the $home_link variables\n> depending on whether the variables were modified. And the documentation\n> would have to explain this complicated arrangement.\n\nFirst, do I understand corrctly that @extra_breadcrumbs are rendered *after*\n$home_link*, and in exactly the same manner?\n\nSecond, I misremembered how $stylesheet / @stylesheets is handled.\nI was thinking more about having in gitweb.perl the following default\ninitialization for @extra_breadcrumbs:\n\n  our @extra_breadcrumbs = ( [ $home_link_str, $home_link ] );\n\nThen one can add breadcrumbs with\n\n  push @extra_breadcrumbs, [ $foo_html, $foo_url ], [\nesc_html($bar_txt), $bar_url ];\n\nBut now I think that we can do better, simply put $home_link_str and $home_link\nin @extra_breadcrumbs / @top_level_breadcrumbs / @nav_breadcrumbs before\nusing it, either via\n\n  unshift @nav_breadcrumbs, [ $home_link_str, $home_link ];\n\nor\n\n  for $breadcrumb ([ $home_link_str, $home_link ], @nav_breadcrumbs) {\n\n... unless we treat home link in some special way (do we?).\n\n\nP.S. It is a bit late, but wouldn't { name => $link_name, href => $link_url }\n(like %features hash) be a better solution than [ $link_name, $link_url ],\ni.e. hashref (named parameters) instead of arrayref (positional parameters).\nYou wouldn't have to remember which is first: text or URL.\n\n-- \nJakub Narebski\n"},{"id":"222566","messageId":"alpine.LSU.2.00.1307041646250.26246@hermes-2.csi.cam.ac.uk","threadId":"34324","inReplyTo":"CANQwDwfCYPBjGfmKOLju-Zey4WrVrXfaymJtu9g1OYvOUfBTcw@mail.gmail.com","subject":"Re: [PATCH] gitweb: allow extra breadcrumbs to prefix the trail","fromName":"Tony Finch","fromEmail":"dot@dotat.at","sentAt":"2013-07-04T15:56:37Z","receivedAt":"2013-07-04T15:56:37Z","isPatch":true,"sender":{"key":"dot@dotat.at","avatar":"https://avatars.githubusercontent.com/u/68429?v=4"},"body":"Jakub Narębski <jnareb@gmail.com> wrote:\n>\n> First, do I understand corrctly that @extra_breadcrumbs are rendered *after*\n> $home_link*, and in exactly the same manner?\n\nBefore the home link, and yes, in the same manner. The extra breadcrumbs\nare for links to parent pages above gitweb in some hierarchy.\n\n> But now I think that we can do better, simply put $home_link_str and $home_link\n> in @extra_breadcrumbs / @top_level_breadcrumbs / @nav_breadcrumbs before\n> using it,\n\nWe could save a line that way:\n\n-       print $cgi->a({-href => esc_url($home_link)}, $home_link_str) . \" / \";\n+       for my $crumb (@extra_breadcrumbs, [ $home_link_str => $home_link ]) {\n+               print $cgi->a({-href => esc_url($crumb->[1])}, $crumb->[0]) . \" / \";\n+       }\n\n> P.S. It is a bit late, but wouldn't { name => $link_name, href => $link_url }\n> (like %features hash) be a better solution than [ $link_name, $link_url ],\n> i.e. hashref (named parameters) instead of arrayref (positional parameters).\n> You wouldn't have to remember which is first: text or URL.\n\nI thought the fat arrow would be mnemonic enough, and less verbose.\n\nTony.\n-- \nf.anthony.n.finch  <dot@dotat.at>  http://dotat.at/\nForties, Cromarty: East, veering southeast, 4 or 5, occasionally 6 at first.\nRough, becoming slight or moderate. Showers, rain at first. Moderate or good,\noccasionally poor at first."},{"id":"222567","messageId":"CANQwDwfNrqZvLNYS6kqZdgX-ab5fK3RmQqAN3qKTW2TGnaDaUg@mail.gmail.com","threadId":"34324","inReplyTo":"alpine.LSU.2.00.1307041646250.26246@hermes-2.csi.cam.ac.uk","subject":"Re: [PATCH] gitweb: allow extra breadcrumbs to prefix the trail","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2013-07-04T16:32:26Z","receivedAt":"2013-07-04T16:32:26Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"On Thu, Jul 4, 2013 at 5:56 PM, Tony Finch <dot@dotat.at> wrote:\n> Jakub Narębski <jnareb@gmail.com> wrote:\n>>\n>> First, do I understand correctly that @extra_breadcrumbs are rendered *after*\n>> $home_link*, and in exactly the same manner?\n>\n> Before the home link, and yes, in the same manner. The extra breadcrumbs\n> are for links to parent pages above gitweb in some hierarchy.\n\nHmmm... I would have thought that they were after home link. I wonder\nif leaving it up to user to configure @extra_breadcrumbs to include $home_link\nin appropriate place (the unshift / push solution to adding to\n@extra_breadcrumbs,\nstarting with $home_link) would be good idea, or over-engineering.\n\nIn what situation do you need those extra breadcrumbs useful? What\nnecessity / itch to scratch is behind idea of this patch?\n\n>> But now I think that we can do better, simply put $home_link_str and $home_link\n>> in @extra_breadcrumbs / @top_level_breadcrumbs / @nav_breadcrumbs before\n>> using it,\n>\n> We could save a line that way:\n>\n> -       print $cgi->a({-href => esc_url($home_link)}, $home_link_str) . \" / \";\n> +       for my $crumb (@extra_breadcrumbs, [ $home_link_str => $home_link ]) {\n> +               print $cgi->a({-href => esc_url($crumb->[1])}, $crumb->[0]) . \" / \";\n> +       }\n\nAnd avoid a bit of code duplication; now we are sure that both\n@extra_breadcrumbs and $home_link are rendered in the same way.\n\n>> P.S. It is a bit late, but wouldn't { name => $link_name, href => $link_url }\n>> (like %features hash) be a better solution than [ $link_name, $link_url ],\n>> i.e. hashref (named parameters) instead of arrayref (positional parameters).\n>> You wouldn't have to remember which is first: text or URL.\n>\n> I thought the fat arrow would be mnemonic enough, and less verbose.\n\nYes, hashref solution is a bit verbose. I don't like abusing fat arrow notation,\nbut here it gives nice mnemonic (hopefully explained in documentation).\n\n-- \nJakub Narebski\n"},{"id":"222570","messageId":"E1UunDD-0004Xd-Vv@hermes-2.csi.cam.ac.uk","threadId":"34324","inReplyTo":"E1Uu3IT-0008U1-3c@hermes-2.csi.cam.ac.uk","subject":"[PATCH v3] gitweb: allow extra breadcrumbs to prefix the trail","fromName":"Tony Finch","fromEmail":"dot@dotat.at","sentAt":"2013-07-04T17:02:12Z","receivedAt":"2013-07-04T17:02:12Z","isPatch":true,"sender":{"key":"dot@dotat.at","avatar":"https://avatars.githubusercontent.com/u/68429?v=4"},"body":"There are often parent pages logically above the gitweb projects\nlist, e.g. home pages of the organization and department that host\nthe gitweb server. This change allows you to include links to those\npages in gitweb's breadcrumb trail.\n\nSigned-off-by: Tony Finch <dot@dotat.at>\nReviewed-by: Jonathan Nieder <jrnieder@gmail.com>\n---\n Documentation/gitweb.conf.txt | 22 ++++++++++++++++++++--\n gitweb/gitweb.perl            |  7 ++++++-\n 2 files changed, 26 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt\nindex ea0526e..305db63 100644\n--- a/Documentation/gitweb.conf.txt\n+++ b/Documentation/gitweb.conf.txt\n@@ -336,8 +336,26 @@ $home_link_str::\n \tused as the first component of gitweb's \"breadcrumb trail\":\n \t`<home link> / <project> / <action>`.  Can be set at build time using\n \tthe `GITWEB_HOME_LINK_STR` variable.  By default it is set to \"projects\",\n-\tas this link leads to the list of projects.  Other popular choice it to\n-\tset it to the name of site.\n+\tas this link leads to the list of projects.  Another popular choice is to\n+\tset it to the name of site.  Note that it is treated as raw HTML so it\n+\tshould not be set from untrusted sources.\n+\n+@extra_breadcrumbs::\n+\tAdditional links to be added to the start of the breadcrumb trail before\n+\tthe home link, to pages that are logically \"above\" the gitweb projects\n+\tlist, such as the organization and department which host the gitweb\n+\tserver. Each element of the list is a reference to an array, in which\n+\telement 0 is the link text (equivalent to `$home_link_str`) and element\n+\t1 is the target URL (equivalent to `$home_link`).\n++\n+For example, the following setting produces a breadcrumb trail like\n+\"home / dev / projects / ...\" where \"projects\" is the home link.\n+----------------------------------------------------------------------------\n+    our @extra_breadcrumbs = (\n+      [ 'home' => 'https://www.example.org/' ],\n+      [ 'dev'  => 'https://dev.example.org/' ],\n+    );\n+----------------------------------------------------------------------------\n \n $logo_url::\n $logo_label::\ndiff --git a/gitweb/gitweb.perl b/gitweb/gitweb.perl\nindex 8d69ada..f429f75 100755\n--- a/gitweb/gitweb.perl\n+++ b/gitweb/gitweb.perl\n@@ -85,6 +85,9 @@ our $project_maxdepth = \"++GITWEB_PROJECT_MAXDEPTH++\";\n # string of the home link on top of all pages\n our $home_link_str = \"++GITWEB_HOME_LINK_STR++\";\n \n+# extra breadcrumbs preceding the home link\n+our @extra_breadcrumbs = ();\n+\n # name of your site or organization to appear in page titles\n # replace this with something more descriptive for clearer bookmarks\n our $site_name = \"++GITWEB_SITENAME++\"\n@@ -3982,7 +3985,9 @@ sub print_nav_breadcrumbs_path {\n sub print_nav_breadcrumbs {\n \tmy %opts = @_;\n \n-\tprint $cgi->a({-href => esc_url($home_link)}, $home_link_str) . \" / \";\n+\tfor my $crumb (@extra_breadcrumbs, [ $home_link_str => $home_link ]) {\n+\t\tprint $cgi->a({-href => esc_url($crumb->[1])}, $crumb->[0]) . \" / \";\n+\t}\n \tif (defined $project) {\n \t\tmy @dirname = split '/', $project;\n \t\tmy $projectbasename = pop @dirname;\n-- \n1.8.3.1.605.g85318f5\n"},{"id":"222568","messageId":"alpine.LSU.2.00.1307041752030.26246@hermes-2.csi.cam.ac.uk","threadId":"34324","inReplyTo":"CANQwDwfNrqZvLNYS6kqZdgX-ab5fK3RmQqAN3qKTW2TGnaDaUg@mail.gmail.com","subject":"Re: [PATCH] gitweb: allow extra breadcrumbs to prefix the trail","fromName":"Tony Finch","fromEmail":"dot@dotat.at","sentAt":"2013-07-04T17:08:51Z","receivedAt":"2013-07-04T17:08:51Z","isPatch":true,"sender":{"key":"dot@dotat.at","avatar":"https://avatars.githubusercontent.com/u/68429?v=4"},"body":"Jakub Narębski <jnareb@gmail.com> wrote:\n>\n> In what situation do you need those extra breadcrumbs useful? What\n> necessity / itch to scratch is behind idea of this patch?\n\nFor an example, see https://git.csx.cam.ac.uk/x/ucs/git/git.git\n\nI have three items in @extra_breadcrumbs which point to the University\nhome page, my department home page, and my git server's home page; there\nare a number of gitolite accounts on the server each of which has a\nproject listing which is where gitweb's home link points.\n\n(I expect to change the link texts to make it less confusing when you\nhappen to be looking at my department's account on the git server...)\n\nour @extra_breadcrumbs = (\n  [ cam => 'http://www.cam.ac.uk/'      ],\n  [ ucs => 'http://www.ucs.cam.ac.uk/'  ],\n  [ git => 'https://git.csx.cam.ac.uk/' ],\n);\n\nThis is in line with our house style (none of which I have implemented on\nthis server yet) - there are other examples of similar breadcrumb trails\nat https://raven.cam.ac.uk and http://new-webmail.hermes.cam.ac.uk\n\nThere is a more generic version of this description and config example in\nv2 of my patch. I hope it is clear enough. I'll send a v3 patch with the\ncode tweak.\n\nTony.\n-- \nf.anthony.n.finch  <dot@dotat.at>  http://dotat.at/\nForties, Cromarty: East, veering southeast, 4 or 5, occasionally 6 at first.\nRough, becoming slight or moderate. Showers, rain at first. Moderate or good,\noccasionally poor at first."},{"id":"222573","messageId":"CANQwDwffPANC-Kb-8sk=UH3EGkG=ON8-TiMRNNS5c5r+rKsW+Q@mail.gmail.com","threadId":"34324","inReplyTo":"alpine.LSU.2.00.1307041752030.26246@hermes-2.csi.cam.ac.uk","subject":"Re: [PATCH] gitweb: allow extra breadcrumbs to prefix the trail","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2013-07-04T17:31:06Z","receivedAt":"2013-07-04T17:31:06Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"On Thu, Jul 4, 2013 at 7:08 PM, Tony Finch <dot@dotat.at> wrote:\n> Jakub Narębski <jnareb@gmail.com> wrote:\n>>\n>> In what situation do you need those extra breadcrumbs useful? What\n>> necessity / itch to scratch is behind idea of this patch?\n>\n> For an example, see https://git.csx.cam.ac.uk/x/ucs/git/git.git\n>\n> I have three items in @extra_breadcrumbs which point to the University\n> home page, my department home page, and my git server's home page; there\n> are a number of gitolite accounts on the server each of which has a\n> project listing which is where gitweb's home link points.\n\nOf course those @external_breadcrumbs are really useful iff they are\nrepeated consistently in at least similar form in all those external pages...\n\n> (I expect to change the link texts to make it less confusing when you\n> happen to be looking at my department's account on the git server...)\n-- \nJakub Narebski\n"},{"id":"222574","messageId":"CANQwDwf56CQZJ25-Lc9WJYeB4Q7_4LVPx45yq9EQ8c17NsJp4g@mail.gmail.com","threadId":"34324","inReplyTo":"E1UunDD-0004Xd-Vv@hermes-2.csi.cam.ac.uk","subject":"Re: [PATCH v3] gitweb: allow extra breadcrumbs to prefix the trail","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2013-07-04T17:42:19Z","receivedAt":"2013-07-04T17:42:19Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"On Thu, Jul 4, 2013 at 7:02 PM, Tony Finch <dot@dotat.at> wrote:\n\n> There are often parent pages logically above the gitweb projects\n> list, e.g. home pages of the organization and department that host\n> the gitweb server. This change allows you to include links to those\n> pages in gitweb's breadcrumb trail.\n>\n> Signed-off-by: Tony Finch <dot@dotat.at>\n> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>\n\nFor what it is worth:\n\nAcked-by: Jakub Narebski <jnareb@gmail.com>\n\n> ---\n>  Documentation/gitweb.conf.txt | 22 ++++++++++++++++++++--\n>  gitweb/gitweb.perl            |  7 ++++++-\n>  2 files changed, 26 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt\n> index ea0526e..305db63 100644\n> --- a/Documentation/gitweb.conf.txt\n> +++ b/Documentation/gitweb.conf.txt\n> @@ -336,8 +336,26 @@ $home_link_str::\n>         used as the first component of gitweb's \"breadcrumb trail\":\n>         `<home link> / <project> / <action>`.  Can be set at build time using\n>         the `GITWEB_HOME_LINK_STR` variable.  By default it is set to \"projects\",\n> -       as this link leads to the list of projects.  Other popular choice it to\n> -       set it to the name of site.\n> +       as this link leads to the list of projects.  Another popular choice is to\n> +       set it to the name of site.  Note that it is treated as raw HTML so it\n> +       should not be set from untrusted sources.\n\nI wonder if we should change this... but it is issue unrelated to current\npatch, which doesn't make situation worse.\n\n> +\n> +@extra_breadcrumbs::\n\n@external_breadcrumbs ???\n\n> +       Additional links to be added to the start of the breadcrumb trail before\n> +       the home link, to pages that are logically \"above\" the gitweb projects\n> +       list, such as the organization and department which host the gitweb\n> +       server. Each element of the list is a reference to an array, in which\n> +       element 0 is the link text (equivalent to `$home_link_str`) and element\n> +       1 is the target URL (equivalent to `$home_link`).\n> ++\n> +For example, the following setting produces a breadcrumb trail like\n> +\"home / dev / projects / ...\" where \"projects\" is the home link.\n> +----------------------------------------------------------------------------\n> +    our @extra_breadcrumbs = (\n> +      [ 'home' => 'https://www.example.org/' ],\n> +      [ 'dev'  => 'https://dev.example.org/' ],\n> +    );\n> +----------------------------------------------------------------------------\n>\n>  $logo_url::\n>  $logo_label::\n> diff --git a/gitweb/gitweb.perl b/gitweb/gitweb.perl\n> index 8d69ada..f429f75 100755\n> --- a/gitweb/gitweb.perl\n> +++ b/gitweb/gitweb.perl\n> @@ -85,6 +85,9 @@ our $project_maxdepth = \"++GITWEB_PROJECT_MAXDEPTH++\";\n>  # string of the home link on top of all pages\n>  our $home_link_str = \"++GITWEB_HOME_LINK_STR++\";\n>\n> +# extra breadcrumbs preceding the home link\n> +our @extra_breadcrumbs = ();\n> +\n>  # name of your site or organization to appear in page titles\n>  # replace this with something more descriptive for clearer bookmarks\n>  our $site_name = \"++GITWEB_SITENAME++\"\n> @@ -3982,7 +3985,9 @@ sub print_nav_breadcrumbs_path {\n>  sub print_nav_breadcrumbs {\n>         my %opts = @_;\n>\n> -       print $cgi->a({-href => esc_url($home_link)}, $home_link_str) . \" / \";\n> +       for my $crumb (@extra_breadcrumbs, [ $home_link_str => $home_link ]) {\n> +               print $cgi->a({-href => esc_url($crumb->[1])}, $crumb->[0]) . \" / \";\n> +       }\n>         if (defined $project) {\n>                 my @dirname = split '/', $project;\n>                 my $projectbasename = pop @dirname;\n> --\n> 1.8.3.1.605.g85318f5\n>\n"},{"id":"222683","messageId":"20130707010550.GK30132@google.com","threadId":"34324","inReplyTo":"E1UunDD-0004Xd-Vv@hermes-2.csi.cam.ac.uk","subject":"Re: [PATCH v3] gitweb: allow extra breadcrumbs to prefix the trail","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-07-07T01:05:50Z","receivedAt":"2013-07-07T01:05:50Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Tony Finch wrote:\n\n> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>\n\nYep, fwiw this version looks perfect to me. :)\n\nThanks.\n"}]}