Новый способ участия в переводе документации

[Антон Исайкин]

Приветствую.

Так сложилось, что времени на перевод и обновление документации у меня все меньше и меньше, и некоторые разделы и отдельные страницы довольно сильно устарели. В то же время, периодически появляются некоторые участники форума, готовые помочь общему делу (о том, на сколько времени хватает такого запала, мы сейчас говорить не будем). Множество раз я отправлял БД документации по различным адресам, чтобы очередной участник занялся обновлением, но выхлоп от этих мероприятий очень незначительный и доставляет проблем куда больше, чем пользы.

Сегодня было решено раз и навсегда(?) решить эту проблему и убить 4 часа чтобы поднять новую для этого сайта систему обновления переводов. Смысл ее таков. Был создан SVN аккаунт на GoogleCode. В новосозданный репозиторий отправляются файлы с расширением .text в формате markdown, которые раз в 10 минут превращаются в html и оказываются на нашем сайте. Правда просто?

Любой, кто хочет дополнить перевод, написать собственный пример или просто исправить опечатку, загружает своим SVN-клиентом репозиторий с документацией, вносит необходимые правки и отправляет коммит в репозиторий. Изменения оказываются на сайте уже через 10 минут.

Временно имеются два ограничения:

• Пока я не понял насколько это эффективно, доступ на запись в репозиторий можно получить только запросив его у меня (письмо на anton@isaykin.ru с темой "SVN code-igniter" и своим google-email'ом в содержании), либо у Александра Макарова, написав ему то же самое на sam@rmcreative.ru.
• Пока уже имеющаяся документация не приведена к markdown'у, все файлы выкладываются в папку test в корне. Т.е. файл, лежащий в репозитории по адресу /trunk/guide/index.text оказывается доступным по URL http://code-igniter.ru/test/index.html.

Предвосхищая вопрос "а почему не wiki", дам развернутый ответ:

• Так было проще и быстрее. Монструозная вики ни в какое сравнение не идет с текущим механизмом. Прикрутить вики, не изменив дизайн и не испортив несколько плюшек (то как вывод на главной странице последних постов и вики-ченджей), стоило бы гораздо больших усилий.
• Если у вас есть права на запись в репозиторий -- сложность обновления страницы сайта ничуть не выше, аналогичной в wiki.
• Есть мысли по дальнейшим упрощениям работы с сайтом. Например возможность коммитом выкладывать файлы и так же просто их обновлять и экспортить другим пользователям.

Спасибо за участие в жизни сайта. Ожидаю комментариев и заявок на подключение к репозиторию.

[bvn]

Лично меня наиболее всего смутил этот самый Марк даун Совершенно без понятия, что оно такое и с чем его едят... Ссылка, даденая вами, не загружается почему-то...

[Антон Исайкин]

http://ru.wikipedia.org/wiki/Markdown
Живой пример http://code.google.com/p/codeigniter-ru ... uting.text

[bvn]

Как в маркдауне создать таблицу или вставить готовый html, если это возможно?

[Sam Dark]

Код: Выделить всё

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

[bvn]

Гмм... Либо тот конвертор не понимает такого синтаксиса, либо я что-то не так делаю, но таблицы у меня не получается... И при том, как задать border="0"?
Я хотел сделать страницу toc.html, поскольку структура содержания в новом мануале тоже поменалась... но видно, зря я начал с этой страницы... топчусь по граблям

[Sam Dark]

border="0" задавать не надо. Это будет сделано через CSS позже. TOC, возможно, будет строится автоматически. Пока не решили. Лучше его пока отложить.

[Антон Исайкин]

На той странице вы можете пока все оформить просто в виде списка. Никакой сложности поменять это на любом этапе нет.

[Антон Исайкин]

Теперь обновление на сайте происходит не каждые 10 минут, а в течение нескольких секунд после того как совершен коммит. Так же теперь доступен для просмотра список файлов в папке test.

[Антон Исайкин]

Прикрутил к получающимся html общий шаблон. Сейчас сразу видно возникающие в разметке ошибки.

[bvn]

Хочется поднять вопрос о целесообразности использования таких слов, как "Роутинг", "Хэлпер" и т. п. при наличии вполне адекватных русских слов "Маршрутизация", "Помощник" и т. д.
Наверное, стоило бы заранее прийти к одному общему решению:
1. использовать нормальные русские слова (Помощник)
2. использовать слова в виде русской транслитерации английских слов (Хэлпер)
3. или же оставить основные термины на английском (Helper).

[bvn]

И еще есть вопрос, как правильно ссылки писать, чтобы они работали и будущем местоположении и сейчас во временном каталоге test?
Когда пишу от корня (/installation/index.html), то ссылка получается без каталога test, а вписывать туда этот каталог или задавать полный урл не хочется, так как потом их все надо будет менять...

[Антон Исайкин]

Писать надо без test, т.е. /installation/index.html.
Чуть позже сделаю так, что /test будет автоматически добавляться на время расположения в этом каталоге. Для удобства.

[Антон Исайкин]

Добавил автозамену. Теперь, если вы делаете ссылку на раздел документации, то необходимо начинать ее со слеша, т.е. вместо

Код: Выделить всё

[Класс URI](libraries/uri.html)

писать

Код: Выделить всё

[Класс URI](/libraries/uri.html)

Парсер же при обработке добавит в начало ссылки "/test". Таким образом на выходе получим удобные ссылки для хождения по тестовой версии.

Код: Выделить всё

<a href="/test/libraries/uri.html">Класс URI</a>

Так же большое спасибо bvn за активное участие в переводе.

[Антон Исайкин]

• Обновил стили и меню, теперь они соответствуют версии 1.7.2 (index.html)
• Теперь после каждого коммита генерируется так же архив с документацией (пока без стилей) с локальными ссылками (user_guide.tar.gz)

[Aen]

Хочется поднять вопрос о целесообразности использования таких слов, как "Роутинг", "Хэлпер" и т. п. при наличии вполне адекватных русских слов "Маршрутизация", "Помощник" и т. д.
Наверное, стоило бы заранее прийти к одному общему решению:
1. использовать нормальные русские слова (Помощник)
2. использовать слова в виде русской транслитерации английских слов (Хэлпер)
3. или же оставить основные термины на английском (Helper).

Можно было бы заняться сразу составлением словаря, а потом уже переводить.
з.ы.: не совсем разобрался с markdown, ну да как-нибудь уже:)

[Sam Dark]

Добавил гайд по переводу: http://code.google.com/p/codeigniter-ru ... ationGuide. Словарь не полный и, возможно, местами избыточен.

[bvn]

Возникла одна сложность, которую хотелось бы исправить в своих файлах, прежде чем...

Короче, в блоках кода, с обратными кавычками `....` не воспринимаются переносы строк и все выводится в одну строку, что не есть хорошо... потом, если вставлена пустая строка, то парсер вообще не воспринимает как блок кода и выводит текст как есть вместе с кавычками...
Примеры: http://code-igniter.ru/test/overview/at_a_glance.html и http://code-igniter.ru/test/general/urls.html

[bvn]

Ладушки, простите, видно уже останется как есть... Собственно эта проблема встречается именно в тех 2 файлах, которые я привел для примера, если что, подправите сами. Я должен сказать, что вот я сделал посильный вклад в это дело, но теперь у меня и со временем стало тугее, да и появилась новая любовь... я бы даже сказал кохана
Теперь если и буду участвовать в подобных делах, то уже там, а не тут. Сорь.

[Слава]

Осилил Shopping Сart Class. При разметке возник трабл: многострочный код не отображается правильно и вместо '<' и '>' отображается &lt;/&gt;. Уж всё пробовал, что-бы поправить своими силами, но не вышло. Перевод строки в файле - Unix-style.

См. тут: http://code-igniter.ru/test/libraries/cart.html

Буду благодарен, если пофиксите, хотел бы перевести еще пару интересных статей.