lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Cassandra Targett <casstarg...@gmail.com>
Subject Re: Shorter URLs to Solr ref-guide?
Date Wed, 12 Jul 2017 13:12:29 GMT
>> To make the conversion simpler and ensure stuff just worked we simply
copied Confluence's anchors, knowing we would remove them later after
some review, which I've been doing with other edits.

In reference to this and inspired by this conversation, I'm making a
sweep through to remove anchors that aren't being used by other pages
for links. I filed SOLR-11050 for this.

On Tue, Jul 11, 2017 at 9:41 AM, Cassandra Targett
<casstargett@gmail.com> wrote:
> I was out on vacation last week, so just catching up to this discussion.
>
> Upfront I'll say I'm +0 on this effort - short URLs are nice, but in
> my mind I balance the effort against its relative priority with other
> things the Ref Guide needs and, for me, this would be lower on my
> list. I don't wish to stop anyone from improving things, though, if
> this is where available skills/energy lie.
>
> That said, a few more specific comments:
>
>>> Register a domain for the guide, e.g. http://solr.guide/ — 12 chars instead
of 30 ($35/yr)
>
> Without "apache.org" in the domain, comments don't work today.
> Supposedly it's possible to make it work, but whatever docs INFRA has
> already written about it are out of date. Investigating that further
> would need to be a step in the process if the permanent URL is
> "solr.guide" instead of "apache.org".
>
>>> Long domain and prefix: http://lucene.apache.org/solr/guide/
>
> It's really no longer than the old domain & prefix:
> https://cwiki.apache.org/confluence/solr/.
>
>>> Write a script that removes the duplicate names in anchors, and run a one-time
conversion
>    e.g. converts #OtherSchemaElements-Similarity to #Similarity
>
> There is a reason why these are there for now and it's because every
> section heading throughout the entire guide must be unique. It's not
> so bad for the HTML version, because each HTML page is a separate
> entity but for the PDF it can cause real problems. The build process
> has a step where it checks the built pages/pdf to ensure all section
> titles or related anchor tags are unique - if there are any
> duplicates, the build fails (it also fails if an anchor doesn't
> exist). So you can't just automatically change them without ensuring
> that there aren't any other pages with a section titled "Similarity",
> or "Examples", or "Parameters", "Input", etc. (the latter 3 being very
> common).
>
> To make the conversion simpler and ensure stuff just worked we simply
> copied Confluence's anchors, knowing we would remove them later after
> some review, which I've been doing with other edits. It's a multi-step
> process - find where might be referring to the anchor you want to
> remove & fix the reference, remove the Confluence-style anchor, then
> run the build to ensure you didn't make a duplicate. And if you did,
> figure out how to change one or more section titles or add simpler
> anchor tags and fix the reference again. A script would help some of
> this, but there will be a long list of things to fix afterwards, and
> many of those probably need some human intervention.
>
> This is also pretty much exactly the same as before, by the way, just
> Confluence had some built-in logic to obscure it in many cases (and
> most probably don't realize how many inter-page links I used to find
> broken all the time).
>
>>> That would probably simplify the publishing instructions as well, if we could
use scp/rsync/ftp instead of svn. Cassandra?
>
> I'm not sure what you're asking me to comment on - perhaps it would
> simplify publishing instructions? Not really sure. It's not that
> onerous today, really, once you do it once. It's nearly exactly the
> same as publishing the javadocs for a release, which is update a
> single file in the CMS then issue a single SVN command to import the
> new pages. And the PDF still requires SVN no matter what you do with
> the online version.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org


Mime
View raw message