Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[init.]协同翻译如何有效嗯哼? #1

Open
ZoomQuiet opened this issue Jan 11, 2018 · 6 comments
Open

[init.]协同翻译如何有效嗯哼? #1

ZoomQuiet opened this issue Jan 11, 2018 · 6 comments

Comments

@ZoomQuiet
Copy link

这是基础问题了...俺的期待是,包含:

  • 如何在本地构建快速编译输出文档网站的配置过程?
    • 有助大家第一时间形成正反馈
    • 问题在如何反馈这种成果?
  • 如何用最 Leo-style 的方式来协同?
@bambooom
Copy link

提供参考: https://github.com/xitu/gold-miner/wiki

@ZoomQuiet
Copy link
Author

@bambooom 是也乎,( ̄▽ ̄)

当然首先要推荐已经成过书的经验哪:
如何组织在线图书工程r · OpenBookProjects/wiki

@ZoomQuiet
Copy link
Author

ZoomQuiet commented Feb 8, 2018

@bambooom 给出的是组织技巧

@OMlalala 是也乎,( ̄▽ ̄)

但是, 俺提出的是如何能展现 Leo 特色的协同体验:

  • 基于 git 自动流程的协同无非两种:
    • 权限分配直怼回仓库立即生效, 由 git 完成 merge, 失败人工处理
    • fork->PR 主持人决策是否接受, 由 git 完成 merge, 失败人工处理
  • 问题在:
    • Leo 文档使用 rST 为格式, 用 Sphinx 编译生成
    • 而 rST 由 .leo 文件管理, 通过内置 RST3 命令汇出
    • 那么问题来了:
      • 是号召大家使用 .leo 来进行翻译
      • 还是直接怼 rST ?
    • 前者当然更加自然, 也能体验 Leo 的妙处
    • 进一步引发的问题:
      • .leo 本质上是 XML 文本
      • 其包含了内容和结构以及文学化注释
      • 以上三者是通过 Leo 系统无缝由 大纲树图+编辑区 自在嗯哼的
      • 那么 git 是否能/应该对不同的人不同的文学化操作进行良好合并?
  • 所以:
    • 至少要检验都使用 .leo 和都使用 .rst 以及混合使用两种工作介质的成员们
    • 相互间如何有效交接/合并成果?
    • 甚至, 是否咨询过其它语言比如说 日语 的 Leo 爱好者在翻译时用什么协同流程?
    • 任何一种工件交接时产生的冲突, 将引发什么问题, 是否能在 Leo 框架中解决?
  • 本质上:
    • 将 rST 设想为代码也是相同的情景
    • 这事儿解决好了, 值得在文档中追加一个章节来分享的...

18.2.19 discuss

~ effective collaborate with .leo for doc.?[via]Advices for Leo documentation in Chinese translated version? - Google 网上论坛

成员间基于 .leo 协同

本地 clone 两个仓库, 分别模拟不同的成员行为

  • CN 仓库复制 LeoDocs.leo -> LeoDocs_ZQ.leo
  • Zh 仓库 git pl, 获得 LeoDocs_ZQ.leo
  • 两个仓库中, 分别对相同的 node 进行编程, 并在本地 git ci
  • CN 先 git pu 到 gh
  • Zh 再 git pu 时

警报

༄  git pu
To github.com:DebugUself/leo-editor-cn.git
 ! [rejected]        master -> master (fetch first)
error: failed to push some refs to '[email protected]:DebugUself/leo-editor-cn.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

根据提示, 进行 pl, 冲突无法自动解决

༄  git pl
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (1/1), done.
remote: Total 3 (delta 2), reused 3 (delta 2), pack-reused 0
Unpacking objects: 100% (3/3), done.
From github.com:DebugUself/leo-editor-cn
   a3e052d..238193e  master     -> origin/master
Auto-merging LeoDocs_ZQ.leo
CONFLICT (content): Merge conflict in LeoDocs_ZQ.leo
Automatic merge failed; fix conflicts and then commit the result.

此时 Zh 仓库中的 LeoDocs_ZQ.leo 指示已改变,再次打开将:

reading: /opt/data/Sites/DU.xmq/LeoDocZh/LeoDocs_ZQ.leo
error parsing /opt/data/Sites/DU.xmq/LeoDocZh/LeoDocs_ZQ.leo
Traceback (most recent call last):
  File "/opt/bin/Leo-5.4/leo/core/leoFileCommands.py", line 1251, in parse_leo_file
    parser.parse(theFile) # expat does not support parseString
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/xml/sax/expatreader.py", line 110, in parse
    xmlreader.IncrementalParser.parse(self, source)
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/xml/sax/xmlreader.py", line 123, in parse
    self.feed(buffer)
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/xml/sax/expatreader.py", line 217, in feed
    self._err_handler.fatalError(exc)
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/xml/sax/handler.py", line 38, in fatalError
    raise exception
SAXParseException: <unknown>:2288:1: not well-formed (invalid token)
read outline in 0.08 seconds

因为 git 自动嵌入的提示文字破坏了 XML 的良构

<<<<<<< HEAD


#1 检验
成员在相同 node 中的可 merge 冲突?</t>
||||||| merged common ancestors
</t>
=======



#1 检验.
成员在相同 node 中的可 merge 冲突?</t>
>>>>>>> 238193ee003840c7ad902d95ad3eb31602443a47
<t tx="ekr.20051202072010"></t>

结论-->失败

成员间基于 .md 协同

  • docs/FAQ.html.md 手工修订
  • 通过 gh 可以完成自动合并
  • 但是, 无论哪个 .leo 都无法感知到 .md 的变化

成员修订 @rst -> @clean 来协同

因为 @clean 能自动识别外部文件的变化,有利协同;
所以,尝试修订原先 @rst 节点为 @clean , 因为包含太多特殊子节点,
将引发:

errors writing: /opt/data/Sites/DU.xmq/LeoDocZh/docs/FAQ.html.md
Orphan node:  @rst-no-head Links (FAQ)
parent node: @clean docs\FAQ.html.md
Orphan node:  Getting Leo
parent node: @clean docs\FAQ.html.md
Orphan node:  Where can I get official releases of Leo?
parent node: Getting Leo
Orphan node:  How do I use git to get the latest sources from Leo's GitHub site?
parent node: Getting Leo
Orphan node:  How can I get recent sn...

追加 @others 后, 又引发:

saved: LeoDocs_ZQ4clean.leo
undefined section: << docstring >>
referenced from: When is using a section better than using a method?
undefined section: << imports >>
referenced from: When is using a section better than using a method?
undefined section: << version history >>
referenced from: When is using a section better than using a method?
undefined section: << globals >>
referenced from: When is using a section better than using a method?
undefined section: << init ivars for writing >>
referenced from: When is using a section better than using a method?
undefined section: << docstring >>
referenced from: How can I organize ....

一系列 rST 声明引用的问题..

也不可用...

ZoomQuiet pushed a commit that referenced this issue Feb 19, 2018
ZoomQuiet pushed a commit that referenced this issue Feb 19, 2018
ZoomQuiet pushed a commit that referenced this issue Feb 19, 2018
ZoomQuiet pushed a commit that referenced this issue Feb 19, 2018
ZoomQuiet pushed a commit that referenced this issue Feb 19, 2018
ZoomQuiet pushed a commit that referenced this issue Feb 19, 2018
ZoomQuiet pushed a commit that referenced this issue Feb 19, 2018
ZoomQuiet pushed a commit that referenced this issue Feb 19, 2018
ZoomQuiet pushed a commit that referenced this issue Feb 19, 2018
ZoomQuiet pushed a commit that referenced this issue Feb 19, 2018
@ZoomQuiet ZoomQuiet changed the title [init.]如何加入协同翻译? [init.]协同翻译如何有效嗯哼? Feb 23, 2018
@ZoomQuiet
Copy link
Author

@DebugUself/du4leo

18.2.22 协同问题定义

~ 通过 zoom.us 快速沟通

记要:

  • 翻译工程尽可能基于 .leo 文档是正义的
  • @rst 本身是单向输出, 无法感知目标文件的变化, 并合理 merge 回自身对应 nodes
  • 基于 P-R 模式的外部协同成本比较大

已有对策:

建议:

  • 翻译工程分阶段组织:
    • 0阶: 怼员基于各自的 .leo 文件, 分片包干儿持续翻译
    • 1阶: 怼员基于相互的 .leo 文件, 分片包干儿交叉校对
    • 2阶: 通过公开渠道, 持续随机校阅, 持续维护/更新
  • 外部爱好者参与:
    • 基于 commit comments 的如何校对 how2proof · DebugUself/leo-editor-cn Wiki, 进一步扩展, 实时对各个版本的翻译成果, 进行逐行点评
    • 结合工程进展宣告的 Issue:
      • 内外成员, 也可以通过 Issue 的回复来提交翻译意见
    • 改造 Sphinx 输出模板, 追加当页点评入口, 从结果页面上持续收集意见

@OMlalala
Copy link
Collaborator

基于 @ZoomQuietcomment 中, 对 成员间基于 .leo 协同 的实验.
下面是自己复现实验的记录, 以确保理解大妈的实验过程及结果.

实验目的

对都使用 LeoDocs.leo 翻译的成员, 检验 git 能否良好合并同一节点的翻译结果?

实验假设/前提

  • 两个成员, 都使用 LeoDocs.leo 翻译
  • 都翻译同一 node, 即 LeoDocs.leo 的第一个 node: **先阅此**

实验环境

实验过程

综述

  • 本地 clone 两个仓库 (LeoDocA, LeoDocB), 分别模拟两个不同的成员行为
  • A 仓库复制 LeoDocs.leo, 改名为 LeoDocs_OM.leo
  • B 仓库获得 LeoDocs_OM.leo
  • 两个仓库中, 分别修改 LeoDocs_OM.leo 的第一个 node 的内容, 并在本地提交修改
  • A 仓库 先推送到远程仓库
  • B 仓库 再推送到远程仓库时, 观察结果

分步记录

本地 clone 两个仓库

git clone https://github.com/DebugUself/playground.git LeoDocA
git clone https://github.com/DebugUself/playground.git LeoDocB

A 仓库文件结构

    ./
    LeoDocs.leo  主翻译文档

B 仓库文件结构

    ./
    LeoDocs.leo  主翻译文档

A 仓库将文件改名, B 仓库获得更新

cd LeoDocsA
cp LeoDocs.leo LeoDocs_OM.leo
git add LeoDocs_OM.leo
git ci -m "add _OM.leo"
git pu

cd ../LeoDocB
git pl

A 仓库文件结构

    ./
    LeoDocs.leo     主翻译文档
    LeoDocs_OM.leo  测试文档

B 仓库文件结构

    ./
    LeoDocs.leo     主翻译文档
    LeoDocs_OM.leo  测试文档

两个仓库中, 分别修改 LeoDocs_OM.leo 的第一个 node 的内容, 并在本地提交修改

  • A 仓库, 编辑 /LeoDocA/LeoDocs_OM.leo#** 先阅此 ** 的内容, 增加文字:
#1 检验.
成员编辑相同 node, 能否 merge 冲突?
位置: LeoDocA/LeoDocs_OM.leo

LeoDocA/LeoDocs_OM.leo#** 先阅此 **

  • B 仓库, 编辑 /LeoDocB/LeoDocs_OM.leo#** 先阅此 ** 的内容, 增加文字:
#1 检验.
成员编辑相同 node, 能否 merge 冲突?
位置: LeoDocB/LeoDocs_OM.leo

注意: 最后一行文字中, 位置是 LeoDocB.., 以造成和 A 仓库的冲突

  • 分别本地提交修改
cd LeoDocA
git add LeoDoc_OM.leo
git ci -m "add test text"

cd LeoDocB
git add LeoDoc_OM.leo
git ci -m "add test text"

A 仓库 先推送到远程仓库

cd LeoDocA
git pu

一切正常

B 仓库 再推送到远程仓库时, 观察结果

警报

➜  LeoDocB git:(master) git pu
To https://github.com/DebugUself/playground.git
 ! [rejected]        master -> master (fetch first)
error: failed to push some refs to 'https://github.com/DebugUself/playground.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

根据提示, 进行 pl, 但冲突无法自动解决

➜  LeoDocB git:(master) git pl
remote: Counting objects: 3, done.
remote: Total 3 (delta 2), reused 3 (delta 2), pack-reused 0
Unpacking objects: 100% (3/3), done.
From https://github.com/DebugUself/playground
   8f48146..8231ed0  master     -> origin/master
Auto-merging LeoDocs_OM.leo
CONFLICT (content): Merge conflict in LeoDocs_OM.leo
Automatic merge failed; fix conflicts and then commit the result.

此时 B 仓库中的 LeoDocs_OM.leo 指示已改变, 使用 Leo 打开

  • the outline pane 只显示一个节点 created root node
  • the log pane 显示
reading: /Users/omlalala/Projects/LeoDocB/LeoDocs_OM.leo
error parsing /Users/omlalala/Projects/LeoDocB/LeoDocs_OM.leo
Traceback (most recent call last):

  File "/usr/local/Cellar/python3/3.6.3/Frameworks/Python.framework/Versions/3.6/lib/python3.6/xml/sax/expatreader.py", line 217, in feed
    self._parser.Parse(data, isFinal)

xml.parsers.expat.ExpatError: not well-formed (invalid token): line 2290, column 1


During handling of the above exception, another exception occurred:


Traceback (most recent call last):

  File "/Users/omlalala/Applications/leo-editor/leo/core/leoFileCommands.py", line 1401, in parse_leo_file
    parser.parse(theFile) # expat does not support parseString

  File "/usr/local/Cellar/python3/3.6.3/Frameworks/Python.framework/Versions/3.6/lib/python3.6/xml/sax/expatreader.py", line 111, in parse
    xmlreader.IncrementalParser.parse(self, source)

  File "/usr/local/Cellar/python3/3.6.3/Frameworks/Python.framework/Versions/3.6/lib/python3.6/xml/sax/xmlreader.py", line 125, in parse
    self.feed(buffer)

  File "/usr/local/Cellar/python3/3.6.3/Frameworks/Python.framework/Versions/3.6/lib/python3.6/xml/sax/expatreader.py", line 221, in feed
    self._err_handler.fatalError(exc)

  File "/usr/local/Cellar/python3/3.6.3/Frameworks/Python.framework/Versions/3.6/lib/python3.6/xml/sax/handler.py", line 38, in fatalError
    raise exception

xml.sax._exceptions.SAXParseException: <unknown>:2290:1: not well-formed (invalid token)

read outline in 0.06 seconds

因为 git 自动嵌入的提示文字破坏了 XML 的良构.

  • 证据
#1 检验.
成员编辑相同 node, 能否 merge 冲突?
<<<<<<< HEAD
位置: LeoDocB/LeoDocs_OM.leo</t>
=======
位置: LeoDocA/LeoDocs_OM.leo</t>
>>>>>>> 8231ed0e87f9c140779e0235e9bb8d5ad8b02bb1
  • 找寻方法
    • 使用其他编辑器(如 sublimetext) 打开 B 仓库的 LeoDoc_OM.leo
    • 找到第一个 node ** 先阅此 **<v> 元素的 t 属性:
      <v t="ekr.20050831195449"><vh>** 先阅此 **</vh></v>
    • 搜索 t 属性, 找到上述文本部分

实验结论

对都使用 LeoDocs.leo 翻译的成员, 检验 git 无法合并同一节点的翻译结果.

TL

0223 init 1h50m

@livingworld
Copy link
Collaborator

livingworld commented Feb 23, 2018

基于 @ZoomQuiet comment 中,在对 成员间基于 .leo 协同 的实验. 并采用@OMlalala comment复现实验的记录框架.下面是自己复现实验的记录, 以确保理解大妈的实验过程及结果.

实验目的

对都使用 LeoDocs.leo 翻译的成员, 检验 git 能否良好合并同一节点的翻译结果?

实验假设/前提

  • 两个成员, 都使用 LeoDocs.leo 翻译
  • 都翻译同一 node, 即 LeoDocs.leo 的第一个 node: **先阅此**

实验环境

实验过程

综述

  • 本地 clone 两个仓库 (LeoDocA, LeoDocB), 分别模拟两个不同的成员行为
  • A 仓库复制 LeoDocs.leo, 改名为 LeoDocs_lw.leo
  • B 仓库获得 LeoDocs_lw.leo
  • 两个仓库中, 分别修改 LeoDocs_lw.leo 的第一个 node 的内容, 并在本地提交修改
  • A 仓库 先推送到远程仓库
  • B 仓库 再推送到远程仓库时, 观察结果

分步记录

本地 clone 两个仓库

git clone https://github.com/DebugUself/playground.git LeoDocA
git clone https://github.com/DebugUself/playground.git LeoDocB

A 仓库文件结构

    ./
    LeoDocs.leo  主翻译文档

B 仓库文件结构

    ./
    LeoDocs.leo  主翻译文档

A 仓库将文件改名, B 仓库获得更新

cd LeoDocsA
xcopy LeoDocs.leo LeoDocs_lw.leo
git add LeoDocs_lw.leo
git commit -m "add _lw.leo"
git push

cd ../LeoDocB
git pull

A 仓库文件结构

    ./
    LeoDocs.leo     主翻译文档
    LeoDocs_lw.leo  测试文档

B 仓库文件结构

    ./
    LeoDocs.leo     主翻译文档
    LeoDocs_lw.leo  测试文档

两个仓库中, 分别修改 LeoDocs_lw.leo 的第一个 node 的内容, 并在本地提交修改

  • A 仓库, 编辑 /LeoDocA/LeoDocs_lw.leo#** 先阅此 ** 的内容, 增加文字:
#1 检验.
成员编辑相同 node, 能否 merge 冲突?
位置: LeoDocA/LeoDocs_lw.leo
  • B 仓库, 编辑 /LeoDocB/LeoDocs_lw.leo#** 先阅此 ** 的内容, 增加文字:
#1 检验.
成员编辑相同 node, 能否 merge 冲突?
位置: LeoDocB/LeoDocs_lw.leo

注意: 最后一行文字中, 位置是 LeoDocB.., 以造成和 A 仓库的冲突

  • 分别本地提交修改
cd LeoDocA
git add LeoDocs_lw.leo
git commit -m "add test text"

cd LeoDocB
git add LeoDocs_lw.leo
git commit -m "add test text"

A 仓库 先推送到远程仓库

cd LeoDocA
git push

一切正常

B 仓库 再推送到远程仓库时, 观察结果

警报

➜  LeoDocB git:(master) git push
To https://github.com/DebugUself/playground
 ! [rejected]        master -> master (fetch first)
error: failed to push some refs to 'https://github.com/DebugUself/playground.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

根据提示, 进行 pull, 但冲突无法自动解决

➜  LeoDocB git:(master) git pull
remote: Counting objects: 3, done.
remote: Total 3 (delta 2), reused 3 (delta 2), pack-reused 0
Unpacking objects: 100% (3/3), done.
From https://github.com/DebugUself/playground
   7202225..5cf55d2  master     -> origin/master
Auto-merging LeoDocs_lw.leo
CONFLICT (content): Merge conflict in LeoDocs_lw.leo
Automatic merge failed; fix conflicts and then commit the result.

此时 B 仓库中的 LeoDocs_lw.leo 指示已改变, 使用 Leo 打开

  • the outline pane 只显示一个节点 created root node
  • the log pane 显示
Leo Log Window
Leo 5.6, build 20171207124619, Thu Dec  7 12:46:19 CST 2017
Not running from a git repo
Python 2.7.13, PyQt version 5.6.2
Windows 10 AMD64 (build 10.0.10586) 
isPython3: False
caching enabled
reading: C:\Users\xxxx\DebugUself\LeoDocsB\LeoDocs_lw.leo
error parsing C:\Users\xxxx\DebugUself\LeoDocsB\LeoDocs_lw.leo
Traceback (most recent call last):

  File "c:\users\xxxx\appdata\local\conda\conda\envs\dataprocess2\lib\site-packages\leo\core\leoFileCommands.py", line 1401, in parse_leo_file
    parser.parse(theFile) # expat does not support parseString

  File "c:\users\xxxx\appdata\local\conda\conda\envs\dataprocess2\lib\xml\sax\expatreader.py", line 110, in parse
    xmlreader.IncrementalParser.parse(self, source)

  File "c:\users\xxxx\appdata\local\conda\conda\envs\dataprocess2\lib\xml\sax\xmlreader.py", line 123, in parse
    self.feed(buffer)

  File "c:\users\xxxx\appdata\local\conda\conda\envs\dataprocess2\lib\xml\sax\expatreader.py", line 217, in feed
    self._err_handler.fatalError(exc)

  File "c:\users\xxxx\appdata\local\conda\conda\envs\dataprocess2\lib\xml\sax\handler.py", line 38, in fatalError
    raise exception

SAXParseException: <unknown>:2290:1: not well-formed (invalid token)

read outline in 0.07 seconds

因为 git 自动嵌入的提示文字破坏了 XML 的良构.

  • 证据
#1 检验.
成员编辑相同 node, 能否 merge 冲突?
<<<<<<< HEAD
位置: LeoDocB/LeoDocs_lw.leo</t>
=======
位置: LeoDocA/LeoDocs_lw.leo</t>
>>>>>>> 5cf55d23963740cef8caa31c85b55c4fb5e30b75
  • 找寻方法
    • 使用其他编辑器(如 sublimetext) 打开 B 仓库的 LeoDocs_lw.leo
    • 找到第一个 node ** 先阅此 **<v> 元素的 t 属性:
      <v t="ekr.20050831195449"><vh>** 先阅此 **</vh></v>
    • 搜索 t 属性, 找到上述文本部分

实验结论

对都使用 LeoDocs.leo 翻译的成员, 检验 git 无法合并同一节点的翻译结果.

TL

0223 init 1h30m

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants