hive-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Lefty Leverenz <leftylever...@gmail.com>
Subject Re: DISCUSS: Hive language manual to be source control managed
Date Mon, 02 Sep 2013 09:06:09 GMT
Last year I converted the entire Language Manual to xdocs, but the project
died from lack of community interest.  So if this goes forward, please
don't start from scratch again -- my files would need to be updated, but
wiki page history makes that fairly easy.  Of course there are several new
docs which would have to be converted from wiki markup to xdocs.

That said, I want to ask:  is this the best use of the development
community's time?  Some of your complaints about the wikidocs are just
glitches in the non-display versions, and presumably those can be fixed or
worked around.  Adding and improving the content seems crucial, but why not
do that in the wiki?

Also, the xdocs weren't removed deliberately -- they broke in December (
HIVE-3896 <https://issues.apache.org/jira/browse/HIVE-3896>) and no one had
the time or inclination to fix them.  Has that situation changed?

-- Lefty Leverenz, devil's advocate



On Sun, Sep 1, 2013 at 5:47 PM, Edward Capriolo <edlinuxguru@gmail.com>wrote:

> I am not sure about BNF. Hive uses antlr so the language itself is never
> described as BNF. Maybe antlr has a tool or clever way to turn the .g file
> into BNF. If it is possible that should be something we do during a
> document generating step. Also if a new feature does change the language
> the theory would be the feature would not be committed unless it had
> associated documentation.
>
>
>
> On Sun, Sep 1, 2013 at 5:44 PM, Stephen Boesch <javadba@gmail.com> wrote:
>
>> Will this allow BNF's for the DDL / DML to be  provided and made up to
>> date  more readily ?
>>
>>
>> 2013/9/1 Edward Capriolo <edlinuxguru@gmail.com>
>>
>>> Over the past few weeks I have taken several looks over documents in our
>>> wiki.
>>> The page that strikes me as alarmingly poor is the:
>>> https://cwiki.apache.org/Hive/languagemanual.html
>>>
>>> This page has several critical broken links such as
>>> https://cwiki.apache.org/Hive/languagemanual-groupby.html
>>> https://cwiki.apache.org/Hive/languagemanual-transform.html
>>>
>>> The language manual used to be in decent shape. At times it had
>>> omissions or was not clear about what version something appeared it, but it
>>> was very usable.
>>>
>>> A long time ago I had began and completed moving the wiki documentation
>>> inside the project as xdoc. After completion, several had a problem with
>>> the xdocs approach. The main complaint was the xdoc approach was too
>>> cumbersome. (However we have basically had a 'turn over' and since that
>>> time I am one of the few active committers)
>>>
>>> The language manual is in very poor shape at the moment with broken
>>> links, incorrect content, incomplete content, and poor coverage of the
>>> actual languages. IMHO the attempts to crowd-source this documentation has
>>> failed. Having a good concise language manual is critical to the success
>>> and adoption of hive.
>>>
>>> I do not believe all of our documentation needs to be in xdoc (as in
>>> every udf, or every input format) but I believe the language manual surely
>>> does.
>>>
>>> Please review the current wiki and discuss the concept of moving the
>>> language manual to source control, or suggest other options.
>>>
>>> Thank you,
>>> Edward
>>>
>>>
>>>
>>
>

Mime
View raw message