Re: Long lines in Docbook sources

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



For what it's worth, many editors have a 'soft wrap' that keeps a paragraph visually manageable while actually keeping it all on one line. I've typically hard wrapped for aforementioned ease of diffing, though.

Re. Publican, I know we have had issues with auto-formatting in the past as auto-formatting tends to newline-and-indent every type of tag, inline OR block. As some inline tags do take whitespace into account (<literal> for example), this leads to weird double-spacing on either side of <literal> text in the output. I'd be very careful of how your script works if you're considering the auto-formatting route (but that probably goes without saying :) ).

You're probably better off establishing clear guidelines on how to format DocBook, say:

* maximum width 80 (though this gets a little narrow after indenting subsections, so recommend max width of about 100)
* indent in [ tabs | x number of spaces ]
* no new line at beginning/end of screen and programlisting tags

...or whatever you decide is important.

Lots of editors will let users add a guide line at the appropriate character width to assist with said formatting, if not an option that hard wraps and indents appropriately.

Cheers, 
Laura Bailey 
Content Author II
Red Hat BNE

On 10/09/2013, at 4:16 AM, Pete Travis <me@xxxxxxxxxxxxxx> wrote:


On Sep 9, 2013 10:43 AM, "John J. McDonough" <wb8rcr@xxxxxxxx> wrote:
>
> On Mon, 2013-09-09 at 09:59 -0400, Ben Cotton wrote:
> > On Mon, Aug 26, 2013 at 5:56 AM, Florian Weimer <fweimer@xxxxxxxxxx> wrote:
> >
> > How about an actual reply instead?
> >
> > > Is this XML source layout the preferred style, or would it be considered
> > > okay to wrap long lines as a separate change before making actual content
> > > changes?
> > >
> > Certainly not preferred by me. :-) I generally set textwidth=80 when I
> > work on the docs, just to keep the lines (and thus diffs) manageable,
> > but it varies wildly. If you want to wrap the lines, I heartily
> > endorse this.
>
> I think the long lines do help a bit with the diffs, but to tell the
> truth, I prefer shorter lines, sometimes, depending on the phase of the
> moon, very short.  I suspect there is some editor somewhere that isn't
> much affected by long lines, because they do appear a lot.
>
> --McD
>

I use org-indent-mode in emacs. I've been trying to get more familiar with vim and I suspect it also has a mode to wrap text on display without inserting actual newlines. Probably Ben's textwidth=80?

If we agree that 80 columns or whatever is preferred, we should find/write a script that would both limit column width and enforce indents to preserve XML inheritance for clarity, and run the script on all our sources in one go. Then share $editor settings going forward.

I'm fairly sure publican doesn't care about whitespace and newlines when building, but I'd like to confirm before doing something drastic - and also confirm extra strings aren't produced when generating POs. Just to be sure.

--Pete

-- 
docs mailing list
docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs

[Index of Archives]     [Fedora Users]     [Fedora Desktop]     [Red Hat 9]     [Yosemite News]     [KDE Users]

  Powered by Linux