[
https://issues.apache.org/jira/browse/SOLR-10749?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16031406#comment-16031406
]
Cassandra Targett commented on SOLR-10749:
------------------------------------------
My objection isn't only the busy-work (although that's part of it, which I'll
mention below), but that it will actually break the docs. There are two aspects
to consider:
First, there shouldn't be any issue with forcing a line-length for paragraphs
of text. The tools we use to build the PDF and HTML versions default to
assuming text in successive lines should go together as a paragraph, and I
believe it also automatically adds the proper space between words/sentences. So
that aspect of it is fine, although it will get messy with subsequent edits and
people not caring enough to make the lines of a paragraph actually flow
properly will personally drive me nuts.
However, I believe there would be an issue with source and literal blocks,
which are meant to be converted exactly the way they are entered into the raw
document. For stuff that's from a config file or actual code, no problem
because it's probably already line-length limited. But we have a lot of
examples of Solr URLs, API calls, request parameters, curl inputs, and even
annotated code that are longer than the limit. Also, rendering into PDF will
wrap them to fit the width of the page, so with those combined, artificially
forcing these might make the examples confusing if they aren't all reviewed to
be sure, and I fear subsequent edits with IDEs forcing line breaks will break
them every single time the page is touched. And, related to this, I don't know
what happens to links to other pages or sites on the internet if they are
broken in the middle by a hard line break.
So, I don't know a way around all that. One compromise I thought of was to say
that all new sentences must be on their own lines, but I doubt that's
sufficient, or even enforceable in any realistic way.
> Should ref guide asciidoc files' line length be limited?
> --------------------------------------------------------
>
> Key: SOLR-10749
> URL: https://issues.apache.org/jira/browse/SOLR-10749
> Project: Solr
> Issue Type: Sub-task
> Security Level: Public(Default Security Level. Issues are Public)
> Reporter: Steve Rowe
> Priority: Minor
>
> From [~dsmiley] and [~janhoy] on SOLR-10290:
> {quote}
> David: Can we auto-linewrap the asciidoc content we've imported somehow? The
> lines are super-long in my IDE (IntelliJ). I can toggle the active editor's
> "soft wrap" at least (View menu, then Active Editor menu).
> Jan: Yea, those lines are long
> {quote}
> From a conversation [~ctargett] and I had on SOLR-10379:
> {quote}
> Steve: I updated the ref guide docs. While I was at it, I installed and used
> the IntelliJ plugin named "Wrap To Column" to wrap at 120 chars (a.k.a. "fill
> paragraph") in the two .adoc files I edited.
> Cassandra: What is the point of this, or even, the big deal about asking your
> IDE to do soft wraps instead?
> Steve: Not all editors support soft-wrapping. There is project consensus to
> wrap code at 120-chars; why make an exception for these doc files?
> {quote}
--
This message was sent by Atlassian JIRA
(v6.3.15#6346)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
