Warning icon

Daniel Shahaf danielsh at elego.de
Wed Aug 7 11:17:07 CDT 2013


C. Michael Pilato wrote on Wed, Aug 07, 2013 at 11:00:33 -0400:
> On 08/07/2013 04:19 AM, Daniel Shahaf wrote:
> > A <warning> box renders with a "No entry" sign:
> > http://svnbook.red-bean.com/nightly/en/svn.basic.in-action.html#svn.basic.svn-repositories.not-working-copy
> >
> > I'm not sure that's a good choice; it might lead a reader to skip the
> > paragraph altogether.  I would suggest this instead (it's in the public
> > domain):
> > https://en.wikipedia.org/wiki/File:Caution_sign_used_on_roads_pn.svg#filehistory
> 
> Seriously, a reader skipping a section of a book altogether, as if it's
> commonplace for authors to write text to be read by ... no one? 

Yes.  The TeXbook has paragraphs marked as "For advanced readers" and
"For very advanced readers" embedded within the main body of the text.
They are intended to be skipped on first reading.

The Python online documentation has paragraphs marked "cPython
implementation detail".  Presumably people who intend their code to be
portable to PyPy or any of the other Python implementations would skip
reading those.

I could definitely see us use a "No Entry" sign to delineate
implementation details, that are currently true but should not be
relied on:

1.5 book:
    <implementation-detail>
       It is safe to copy a live FSFS repository with <tt>rsync</tt>.
    </implementation-detail>

1.6 book:
    <warning>
       It is not safe to copy a live FSFS repository with <tt>rsync</tt>.
    </warning>

Thanks for asking.

Daniel




More information about the svnbook-dev mailing list