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-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org
