You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Gabriela Gibson <ga...@gmail.com> on 2012/12/19 13:40:42 UTC
[PATCH] code file names linkified in general.html of the Hacking
Guide
[[[
Linkified code file names in file general.htm of the Hacking Guide
Converted file names into links pointing to the current revision on page:
http://subversion.apache.org/docs/community-guide/general.html#code-to-read
Converted directory names into links pointing to the current revision on
page:
http://subversion.apache.org/docs/community-guide/general.html#directory-layout
Patch by: Gabriela Gibson <ga...@gmail.com>
]]]
regards,
Gabriela
ps.: The credit note was just for practice :>
Re: [PATCH] code file names linkified in general.html of the Hacking
Guide
Posted by Stefan Sperling <st...@elego.de>.
On Wed, Dec 19, 2012 at 03:48:25PM +0200, Daniel Shahaf wrote:
> Gabriela Gibson wrote on Wed, Dec 19, 2012 at 12:40:42 +0000:
> > in APR (look in 'apr/include/'):</p>
> >
> > <ul>
> > -<li><p>memory pools: apr_pools.h</p></li>
> > -<li><p>filesystem access: apr_file_io.h</p></li>
> > -<li><p>hashes and arrays: apr_hash.h, apr_tables.h</p></li>
> > +<li><p>memory pools: <a href="https://svn.apache.org/repos/asf/subversion/trunk/subversion/include/apr_pools.h">apr_pools.h</a></p></li>
>
> Broken links. If you want to link to them in APR's svn tree that's
> fine, but I'm not sure whether you should link to the apr 1.x or 2.x
> versions of these headers?
Daniel means this svn tree: http://svn.apache.org/repos/asf/apr/apr/
Which is where the APR project (http://apr.apache.org) has its source code.
Just in case this wasn't clear.
I'd say link to APR 1.5.x, which is the current release in the 1.x
series: http://svn.apache.org/repos/asf/apr/apr/branches/1.5.x/include/apr_pools.h
It doesn't really matter if this link gets stale over time.
Curious readers will find newer versions of the file on their own.
Re: [PATCH] code file names linkified in general.html of the
Hacking Guide
Posted by Daniel Shahaf <da...@elego.de>.
Gabriela Gibson wrote on Wed, Dec 19, 2012 at 12:40:42 +0000:
> in APR (look in 'apr/include/'):</p>
>
> <ul>
> -<li><p>memory pools: apr_pools.h</p></li>
> -<li><p>filesystem access: apr_file_io.h</p></li>
> -<li><p>hashes and arrays: apr_hash.h, apr_tables.h</p></li>
> +<li><p>memory pools: <a href="https://svn.apache.org/repos/asf/subversion/trunk/subversion/include/apr_pools.h">apr_pools.h</a></p></li>
Broken links. If you want to link to them in APR's svn tree that's
fine, but I'm not sure whether you should link to the apr 1.x or 2.x
versions of these headers?
RE: [PATCH] code file names linkified in general.html of the Hacking Guide
Posted by Bert Huijben <be...@qqmail.nl>.
> -----Original Message-----
> From: Gabriela Gibson [mailto:gabriela.gibson@gmail.com]
> Sent: woensdag 19 december 2012 13:41
> To: dev@subversion.apache.org
> Subject: [PATCH] code file names linkified in general.html of the Hacking
> Guide
>
> [[[
> Linkified code file names in file general.htm of the Hacking Guide
>
> Converted file names into links pointing to the current revision on page:
>
> http://subversion.apache.org/docs/community-guide/general.html#code-
> to-read
>
> Converted directory names into links pointing to the current revision on
> page:
>
> http://subversion.apache.org/docs/community-
> guide/general.html#directory-layout
>
> Patch by: Gabriela Gibson <ga...@gmail.com>
> ]]]
I like the idea, but maybe we should link to the generated documentation
below http://subversion.apache.org/docs/api/latest/ instead of directly to
the source files?
Bert
>
> regards,
>
> Gabriela
>
> ps.: The credit note was just for practice :>
>
>
Re: [PATCH] code file names linkified in general.html of the
Hacking Gttuide
Posted by Daniel Shahaf <d....@daniel.shahaf.name>.
Gabriela Gibson wrote on Thu, Dec 20, 2012 at 21:05:39 +0000:
> (Optional: Please use wget to download an uncorrupted original to modify
> instead of a copy saved by your browser.)
Just note that we use SSI (server-side includes) to include the
top and left navigation bars on each page, so the served pages are not
identical to those in svn. This of course doesn't affect the common
case (since the unidiff will apply with offset $(wc -l site-nav.html)),
but since you write this advice you should be aware of the issue.
> ]]]
>
> David Shahaf wrote:
>
> > I'd say link to APR 1.5.x, which is the current release in the 1.x
> > series:
This quote is by Stefan Sperling.
Re: [PATCH] code file names linkified in general.html of the Hacking
Gttuide
Posted by Stefan Sperling <st...@elego.de>.
On Thu, Dec 20, 2012 at 09:05:39PM +0000, Gabriela Gibson wrote:
> Most of this would not have happened if I had svn protection here I
> guess -- would it be worthwhile to add the html part of the project
> to the revision tree?
It is in the repository at https://svn.apache.org/repos/asf/subversion/site
Whenever we make a commit there the change show up on the web site.
So to submit changes to the site, just send patch generated from a
working copy checked out from the above URL.
> Network access isn't always a givens and the guide is a key
> document, it'll be nice to have in the /doc dir.
The community guide is within the above URL as well :)
See publish/docs/community-guide/
> As an aside, Lynx also saves a a bad copy. I didn't expect that --
> 10 years ago this all worked just fine! :o)
Hah!
> >I haven't checked all other tags for similar errors, not enough time.
> >It might be a good idea to run an XHTML validator on the modified file.
> >
>
> It might be useful to add the info of how to submit web pages
> patches to the the 'log messages' section of the guide (http://subversion.apache.org/docs/community-guide/conventions.html#log-messages)
> for example:
>
> [[[
> When writing log messages for patches regarding the project's web pages, eg:
>
> http://subversion.apache.org/docs/communityguide/somepage.html#section-name
>
> list the names of files modified in the patch in the log message,
> relative to site/publication and list anchors of sections added or
> modified like this:
>
> * docs/community-guide/some_page.html
> (section-name): fixed issue xyz
>
> Please validate the new hmtl file with a XHTML validator and check
> all the links before submitting the patch.
>
> (Optional: Please use wget to download an uncorrupted original to
> modify instead of a copy saved by your browser.)
> ]]]
I agree, it would be useful to mention this in the community guide.
Could you send a patch to the website that makes this change,
based on a working copy of https://svn.apache.org/repos/asf/subversion/site ?
That would be great. Thanks!
Re: [PATCH] code file names linkified in general.html of the Hacking
Gttuide
Posted by Gabriela Gibson <ga...@gmail.com>.
On 19/12/12 12:59, Stefan Sperling wrote:
> Here it looks like we'll end up closing <li> twice. Was that on purpose?
Oops :( -- Firefox saved a mangled original I worked on and when I
looked at the messy patch this produced, I decided to get a fresh copy
and to 'buff it out' by copying the changes manually from the broken
copy and thus I introduced this error.
Most of this would not have happened if I had svn protection here I
guess -- would it be worthwhile to add the html part of the project to
the revision tree?
Network access isn't always a givens and the guide is a key document,
it'll be nice to have in the /doc dir.
As an aside, Lynx also saves a a bad copy. I didn't expect that -- 10
years ago this all worked just fine! :o)
> I haven't checked all other tags for similar errors, not enough time.
> It might be a good idea to run an XHTML validator on the modified file.
>
It might be useful to add the info of how to submit web pages patches to
the the 'log messages' section of the guide
(http://subversion.apache.org/docs/community-guide/conventions.html#log-messages)
for example:
[[[
When writing log messages for patches regarding the project's web pages, eg:
http://subversion.apache.org/docs/communityguide/somepage.html#section-name
list the names of files modified in the patch in the log message,
relative to site/publication and list anchors of sections added or
modified like this:
* docs/community-guide/some_page.html
(section-name): fixed issue xyz
Please validate the new hmtl file with a XHTML validator and check all
the links before submitting the patch.
(Optional: Please use wget to download an uncorrupted original to modify
instead of a copy saved by your browser.)
]]]
David Shahaf wrote:
> I'd say link to APR 1.5.x, which is the current release in the 1.x
> series:
http://svn.apache.org/repos/asf/apr/apr/branches/1.5.x/include> /apr_pools.h
If it generates a continuous liability maybe this part is best left
untouched, or perhaps preserved in a static file?
Re: [PATCH] code file names linkified in general.html of the Hacking
Guide
Posted by Stefan Sperling <st...@elego.de>.
On Wed, Dec 19, 2012 at 12:40:42PM +0000, Gabriela Gibson wrote:
> [[[
> Linkified code file names in file general.htm of the Hacking Guide
>
> Converted file names into links pointing to the current revision on page:
>
> http://subversion.apache.org/docs/community-guide/general.html#code-to-read
>
> Converted directory names into links pointing to the current revision on
> page:
>
> http://subversion.apache.org/docs/community-guide/general.html#directory-layout
>
> Patch by: Gabriela Gibson <ga...@gmail.com>
> ]]]
>
Can you please list the names of files you're modifying in the patch
in the log message? We usually list them relative to site/publish and
list anchors of sections modified like this:
* docs/community-guide/general.html
(code-to-read): Linkified code file names.
and so on. This formatting matches what is used for code contributions
and makes the actual change description stand out better.
> --- general-orig.html 2012-12-19 11:53:49.880600246 +0000
> +++ general-new.html 2012-12-19 12:22:42.253190871 +0000
> Stuff that works with Subversion, but that Subversion doesn't
> depend on, and that is maintained by individuals who may or may
> not participate in Subversion development. Code in contrib/ is
> open source, but may have a different license or copyright holder
> than Subversion itself.</p>
> </li>
> -<li><p><tt>packages/</tt><br>
> +</li>
Here it looks like we'll end up closing <li> twice. Was that on purpose?
I haven't checked all other tags for similar errors, not enough time.
It might be a good idea to run an XHTML validator on the modified file.