Open Stack

Hello Remo,

I am not too much familiar with asciidoc, but would you share the 
followings?

- "100 times easier" means overall efficiency or just writing? Is there 
statistics on that?
- Is asciidoc also useful for describing much more contextual 
description such as tables, code blocks, api documents, custom themes, 
and so on?
- Is there some a kind of well-known tool-chains for asciidoc to support 
documentation and building with translated resources (e.g., po files) 
and for publication?

IMO choosing of asciidoc is also dependent to Documentation team I think.

Akihiro and me are saying that current Sphinx tool-chain sets which we 
have experienced and are familiar can help on building
edge computing whitepaper translation support without too much effort.


@Frank,
 > Customizing things with Latex like fonts, color, background picture, 
front picture?

I previously worked PDF files with basic theme stuff: e.g., 
https://docs.openstack.org/ocata/install-guide-obs/InstallGuide.pdf ,
although the stuff is not very easy - it would take some effort.
https://review.openstack.org/#/c/430263/ and 
https://review.openstack.org/#/c/439712/ would be cool reference for you 
I think.

For me, implementing PDF & publishing translated documents for project 
repositories has higher priority to me so I could not help building 
translated PDFs
for edge computing whitepaper with Sphinx stuff right now.


With many thanks,

/Ian

Remo Mattei wrote on 5/30/2018 11:16 PM:
> I have done this Frank but asciidoc is 100 times easier to deal than Sphinx.
>
> Remo
>
>> Il giorno 30 mag 2018, alle ore 01:03, Frank Kloeker <eumel at arcor.de> ha scritto:
>>
>> Good morning,
>>
>> thanks to Akihiro and Ian to pushing that topic forward. What about PDF creation in Sphinx? Have you some experience to customize things with Latex like fonts, color, background picture, front picture? I tried this but without sucess.
>>
>> kind regards
>>
>> Frank
>>
>> Am 2018-05-30 01:17, schrieb Akihiro Motoki:
>>> Hi Ian,
>>> Thanks for more considerations.
>>> 2018年5月30日(水) 0:42 Ian Y. Choi <ianyrchoi at gmail.com>:
>>>> Hello Akihiro,
>>>> Looks so amazing! Thanks a lot for your lots of progress on
>>>> translated
>>>> edge computing white paper publication
>>>> with RST-based method, which is much preferred from I18n team, Docs
>>>> team, and all upstream projects.
>>>> In my honest opinion, using *one* unified tool in all OpenStack area
>>>> including official projects and publication
>>>> would be best, but more discussion and agreement on multiple
>>>> different
>>>> teams (+ Foundation) would be needed I think.
>>>> When I attended to a Forum on ops-guide during Summit last week, I
>>>> found
>>>> that ops-guide would want to convert from Wiki-based format to
>>>> RST-based
>>>> format.
>>>> It would be pretty nice if we all use RST-based documents to many
>>>> places, but more things (e.g., current implementation,
>>>> maintenance, ...) need to be considered I think.
>>> RST can start from simpler cases and potentially supports more
>>> complicated cases.
>>> I personally prefer to using RST-based documents everywhere.
>>>> Now I would like to ask more opinions on:
>>>> - @amotoki: How long does it take to convert original text file +
>>>> texts
>>>> on a PDF file to RST-based formats?
>>>> Did you do it manually and would it be also
>>>> rather easy for other members such as me or Foundation staff?
>>> Setting up the initial repo and converting the original text into RST
>>> format was really simple.
>>> It tooks only less than our hour.
>>> In this case, I took extra two or three hous to cover the following,
>>> but I don't think it always happens.
>>> - to adjust Japanese translation to cover differences between the
>>> published PDF version
>>>   and the text uploaded to Zanata
>>> - to automate the above differences for other languages
>>>> - @Foundation: Is it okay for translated white papers to publish
>>>> with
>>>> RST-based tools as Akihiro did, since RST-based tools
>>>> are much easier to publish translated
>>>> documents and sync translated resources (po files)?
>>>> - @Foundation: OpenStack documents use CC BY 3.0. Would it be fine
>>>> for
>>>> translated white papers to use similar CC
>>>> rather than CC BY-ND 4.0, for original
>>>> edge
>>>> computing white paper document or cause intellectual issues?
>>> I don't mind using different licenses even if they don't block
>>> community collaborations.
>>> We have a number of documentations (TC governed project documents, SIG
>>> documents, .....),
>>> so it would be nice if we select licenses consistently.
>>>> - All (including translators): For design stuff, just making use of
>>>> openstackdocstheme would be pretty fine?
>>>> For example, I forked from Akihiro's github repo, and
>>>> published
>>>> using openstackdocstheme
>>>> to https://ianychoi.github.io/edge-computing-whitepaper/
>>>> (e.g.,
>>>> https://ianychoi.github.io/edge-computing-whitepaper/ja/ ).
>>> Using openstackdocstheme would be nice when it is published in
>>> openstack.org [1].
>>> openstackdocstheme is intended to use for OpenStack *official*
>>> projects,
>>> so I just didn't use it as an initial effort.
>>> If we continue to use another variants of CC and openstackdocstheme,
>>> we can update openstackdocstheme to support more CC licensees.
>>> Thanks,
>>> Akihiro
>>>> With many thanks,
>>>> /Ian
>>>> Akihiro Motoki wrote on 5/29/2018 11:37 PM:
>>>>> Hi Ildiko and all,
>>>>> I am happy to hear that HTML-based publishing is now on the table
>>>> :)
>>>>> I am synced with Ian and Frank on this topic, though I failed to
>>>> join
>>>>> the conversation at Vancouver.
>>>>> RST based process is used much in the community and translation
>>>>> publishinng of project docs which Ian and us are working on will
>>>> make
>>>>> the continuous publishing easier.
>>>>> I am happy to help setting up a new doc infrastructure and/or
>>>>> publishing translations.
>>>>> Regarding the license, CC BY-ND license turned out a bit too
>>>> strict in
>>>>> our collaborative works when I checked the current one.
>>>>> Hopefully we can get a good conclusion for further similar cases.
>>>>> Thanks,
>>>>> Akihiro
>>>>> 2018年5月29日(火) 23:19 Ildiko Vancsa <ildiko.vancsa at gmail.com
>>>>> <mailto:ildiko.vancsa at gmail.com>>:
>>>>> Hi Akihiro and All,
>>>>> Thank you for your efforts on helping with publishing the
>>>> white
>>>>> paper in additional languages.
>>>>> I talked to Ian and Frank last week about this topic and the
>>>>> conundrum on the Foundation side whether or not to do the
>>>> print
>>>>> version for the translations as that is what slows down the
>>>>> process a lot due to the design work it requires.
>>>>> We got to the conclusion with our team from the Foundation
>>>> (cc’ed
>>>>> Allison, Jimmy and Wes) to do HTML-based publishing to reduce
>>>> this
>>>>> overhead. We need to clarify now on the process and as Jeremy
>>>>> indicated the licensing as well.
>>>>> Thanks,
>>>>> Ildikó
>>>>>> On 2018. May 29., at 15:50, Jeremy Stanley
>>>> <fungi at yuggoth.org
>>>>> <mailto:fungi at yuggoth.org>> wrote:
>>>>>>> On 2018-05-29 18:50:23 +0900 (+0900), Akihiro Motoki wrote:
>>>>>>> [...]
>>>>>>> NOTE: Anyway I need to grant it from the foundation because
>>>> CC
>>>>>>> Attribution-NoDerivatives 4.0 International license does
>>>> not allow
>>>>>>> me to share translations without permission. I updated this
>>>> files
>>>>>>> only for discussion and will close this soon.
>>>>>> [...]
>>>>>> It seems like this is a really poor choice of license as
>>>> it's
>>>>>> impairing open collaboration. Even Creative Commons suggests
>>>> that
>>>>>> the CC BY-ND license is unsuitable for free cultural works:
>>>> https://creativecommons.org/share-your-work/public-domain/freeworks/
>>>>>> We should see about getting this changed to CC BY like is
>>>> used for
>>>>>> other collaborative works produced by our community.
>>>>>> --
>>>>>> Jeremy Stanley
>>>>>> _______________________________________________
>>>>>> openstack-sigs mailing list
>>>>>> openstack-sigs at lists.openstack.org
>>>>> <mailto:openstack-sigs at lists.openstack.org>
>>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-sigs
>>>>> _______________________________________________
>>>>> openstack-sigs mailing list
>>>>> openstack-sigs at lists.openstack.org
>>>>> <mailto:openstack-sigs at lists.openstack.org>
>>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-sigs
>>>>> _______________________________________________
>>>>> OpenStack-I18n mailing list
>>>>> OpenStack-I18n at lists.openstack.org
>>>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n
>>> Links:
>>> ------
>>> [1] http://openstack.org
>>> _______________________________________________
>>> openstack-sigs mailing list
>>> openstack-sigs at lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-sigs
>>
>> _______________________________________________
>> OpenStack-I18n mailing list
>> OpenStack-I18n at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n
>
> _______________________________________________
> OpenStack-I18n mailing list
> OpenStack-I18n at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n