You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by "Cassandra Targett (JIRA)" <ji...@apache.org> on 2017/07/18 00:30:00 UTC
[jira] [Comment Edited] (SOLR-10301) Create meta-documentation for
how to write in asciidoc
[ https://issues.apache.org/jira/browse/SOLR-10301?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16090862#comment-16090862 ]
Cassandra Targett edited comment on SOLR-10301 at 7/18/17 12:29 AM:
--------------------------------------------------------------------
I would like to publish these meta-docs online somewhere, and I've thought of a few possibilities:
* Manually convert them to HTML and put them on the website, maybe under http://lucene.apache.org/solr/guide. Maintenance would be a (minor) issue here. I really don't want to introduce a manual process though.
* Put them all in the Solr Wiki. I spent approximately 10 seconds thinking about how much fun it would be to take AsciiDoc and jam it into MarkDown ... and then discarded this idea.
* Publish them with the rest of the Guide. This is my preferred idea, so I thought some more about it...
My proposal:
* Move the directory {{solr-ref-guide/meta-docs}} and its contents to {{solr-ref-guide/src/meta-docs}} so they are found by the build process.
* Create a new page {{how-to-contribute.adoc}} that will have different content depending on the format:
** HTML will use the {{include}} macro to pull the pages that are currently in {{solr-ref-guide/meta-docs}} into one large page. An alternate idea would be for them to be separate pages, but I rather like them being in a discreet directory from the other content.
** PDF will have an intro paragraph and point users to the online version of {{how-to-contribute.html}}. The reason I wanted to do this is the PDF is already really, really long, and it feels like content that is better served online instead.
* In the HTML version, the last item in the sidebar navigation will be a new top-level heading "How to Contribute".
It would also be possible to only publish the content if the page is (or is not) a DRAFT - but, personally I think it's fine to publish it in the "live" HTML version.
If there aren't any objections or better ideas, I'll get this done tomorrow.
was (Author: ctargett):
I would like to publish these meta-docs online somewhere, and I've thought of a few possibilities:
* Manually convert them to HTML and put them on the website, maybe under http://lucene.apache.org/solr/guide. Maintenance would be a (minor) issue here. I really don't want to introduce a manual process though.
* Put them all in the Solr Wiki. I spent approximately 10 seconds thinking about how much fun it would be to take AsciiDoc and jam it into MarkDown ... and then discarded this idea.
* Publish them with the rest of the Guide. This is my preferred idea, so I thought some more about it...
My proposal:
* Move the directory {{solr-ref-guide/meta-docs}} and its contents to {{solr-ref-guide/src/meta-docs}} so they are found by the build process.
* Create a new page {{how-to-contribute.adoc}} that will have different content depending on the format:
** HTML will use the {{include}} macro to pull the pages that are currently in {{solr-ref-guide/meta-docs}} into one large page.
** PDF will have an intro paragraph and point users to the online version of {{how-to-contribute.html}}. The reason I wanted to do this is the PDF is already really, really long, and it feels like content that is better served online instead.
* In the HTML version, the last item in the sidebar navigation will be a new top-level heading "How to Contribute".
It would also be possible to only publish the content if the page is (or is not) a DRAFT - but, personally I think it's fine to publish it in the "live" HTML version.
If there aren't any objections or better ideas, I'll get this done tomorrow.
> Create meta-documentation for how to write in asciidoc
> ------------------------------------------------------
>
> Key: SOLR-10301
> URL: https://issues.apache.org/jira/browse/SOLR-10301
> Project: Solr
> Issue Type: Sub-task
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation
> Reporter: Cassandra Targett
> Assignee: Cassandra Targett
>
> If we want to encourage new users and non-committers to contribute patches for the Ref Guide, we should document some basics on how to write in Asciidoc(tor) format, and how to install/use various tools to improve the experience.
> Some basic style guidelines may also be helpful, to ensure a consistent experience once docs are published.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org