Jump to content
Korean Random
Sign in to follow this  
sech_92

Актуализация документации к XVM

Recommended Posts

На данный момент имеем вот что:

dev.modxvm.com/xvm/src/tip/release/doc/

Перечень макросов в 4 разделе файлов readme-*.txt неактуален и тут было решено это исправить.

То решение, что вижу я - сделать несколько файлов macros-*.txt с комментариями на разных языках и перенести туда всё о макросах (расширенный формат, примеры и всё до информации об иконках)

 

Попутно я внесу мелкие правки вроде замены имени папки @Default на актуальную default.
Тему создаю чтоб, возможно, получить другие решения, обсудить и выбрать. Но это будет уже завтра :)

Share this post


Link to post

Short link
Share on other sites

 

 

Тему создаю чтоб, возможно, получить другие решения, обсудить и выбрать.
Можно html-ку замутить, чтобы с навигацией проще было. Простенькую, чтобы гемора не было при обновлении
  • Upvote 3

Share this post


Link to post

Short link
Share on other sites

 

 

So, one macro per file?
No, one language per file. We have 5 translations of readme by now. So if we move macros description to separate files - we need at leas 5 translations of those files.

Share this post


Link to post

Short link
Share on other sites

То решение, что вижу я - сделать несколько файлов macros-*.txt с комментариями на разных языках и перенести туда всё о макросах (расширенный формат, примеры и всё до информации об иконках)

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

Именно поэтому я перестал поддерживать readme и перешел на macros.txt.

В общем, я за то, чтобы макросы были только на английском. Кто хочет локализировать - пожалуйста, но без моего участия.

Edited by sirmax

Share this post


Link to post

Short link
Share on other sites
Кто хочет локализировать - пожалуйста, но без моего участия.

Я не знаю кто переводит на польский и чешский. Русскую "копию" стоит сделать, мне кажется. 

Edited by sech_92

Share this post


Link to post

Short link
Share on other sites

Я не знаю кто переводит на польский и чешский. Русскую "копию" стоит сделать, мне кажется. 

Если сделать, она будет такой же не актуальной, как и французской и польской. Я бы и ChangeLog только на английском вел. Два языка - это крайне не удобно.

Share this post


Link to post

Short link
Share on other sites

Два языка - это крайне не удобно.

С позиции разработчика, я понимаю. Но пользователям с не очень хорошим английским это усложнит жизнь. Посты "тампаанглицки, яничивонепонял" провоцировать не хочется.

Share this post


Link to post

Short link
Share on other sites

Я не знаю кто переводит на польский и чешский. Русскую "копию" стоит сделать, мне кажется. 

 

 

Siemka!

 

But i still think some parts of readme are redundant with macros.txt and it should be cleaned.

 

 

And i'm not sure it is necessary to translate to other languages besides English as there are not that many advanced modders.

Share this post


Link to post

Short link
Share on other sites

Если сделать, она будет такой же не актуальной, как и французской и польской. Я бы и ChangeLog только на английском вел. Два языка - это крайне не удобно.

Вот вам мнение профессионального программера-системщика, специализируещегося на писании RTOS. 

1. Вы вводите новые или изменяете старые элементы языка, а их описание выкладываете с запозданием.

2. Описания макросов неполные и порой не совсем корректные. Как можно развивать язык, не имея его спецификации и описания? Например, стало доступно использование вложенных макросов. Ура! НО! Какой уровень вложенности допустим? Все ли макросы допускают вложения? Что насчет совместимости типов? 

3. Указания на похожесть стандартным функциям только запутывают.

4. И т.д. и т.п. ......

 Предлагаю сделать толковое описание всех элементов (со структурой описания как у ADOBE, X(Y)ML, C или PASKAL). Примеры приветствуются, но это не догма.

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

 

Вирт и Дейкстра Вам в помощь!

С уважением.

 

P.S. А на русском или английском Вы напишите не суть Важно. Вы, вероятно, лучше знаете аудиторию пользователей.

P.P.S. ChangeLog - это ИНФОРМАЦИОННОЕ сообщение, но никак не описательная часть нововведений.

Edited by Next

Share this post


Link to post

Short link
Share on other sites

Предлагаю сделать толковое описание всех элементов

Мы только за. Дерзай.

Share this post


Link to post

Short link
Share on other sites

Мы только за. Дерзай.

Я, увы, не разработчик. А делать это должно именно им.

  • Upvote 1
  • Downvote 1

Share this post


Link to post

Short link
Share on other sites

 

 

увы, не разработчик

 

Если "увы" искреннее, то это исправимо. Проект открытый, разработчиком может стать каждый.

 

 

 

А делать это должно именно им.

 

Здесь никому ничего не "должно". Всё делается на добровольных основах по принципу "как есть", и каждый волен работать над проектом в области своих интересов и для своего удовольствия.

  • Upvote 1

Share this post


Link to post

Short link
Share on other sites

Если "увы" искреннее, то это исправимо. Проект открытый, разработчиком может стать каждый.

 

 

 

 

Здесь никому ничего не "должно". Всё делается на добровольных основах по принципу "как есть", и каждый волен работать над проектом в области своих интересов и для своего удовольствия.

"увы" - это искренне. Если это реальное предложение - то я над этим задумаюсь.

Разумеется не должнЫ. А я говорил о должнО. Это про культуру создания языков. Уверен, что никто не хочет превратить замечательный проект в закрытый клуб.

 

P.S.Если я решусь влиться в Ваши ряды - что я должен для этого буду сделать?

Share this post


Link to post

Short link
Share on other sites

Если я решусь влиться в Ваши ряды - что я должен для этого буду сделать?

Что посчитаете нужным и что интересным для вас. Работы всегда много по любым направлениям: от поддержки пользователей до написания кода и документации. Поскольку у вас есть некоторый опыт создания документации, уместно было бы начать, например, с создания топиков, более подробно освещающих обозначенные выше вопросы, или с pull-request'а с вашими правками к существующим фалам документации.

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

 

Если это реальное предложение - то я над этим задумаюсь.

Вполне реальное и обращённое также абсолютно ко всем желающим принимать участие в развитии проекта :)

Share this post


Link to post

Short link
Share on other sites

 сделать несколько файлов macros-*.txt с комментариями на разных языках

Начал для ру: http://www.koreanrandom.com/forum/topic/21642-%D0%BC%D0%B0%D0%BA%D1%80%D0%BE%D0%BF%D0%BE%D0%B4%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B8-%D0%B2-xvm-%D0%BF%D0%B5%D1%80%D0%B5%D0%B2%D0%BE%D0%B4-macros-for-xvm/

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

Share this post


Link to post

Short link
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

Sign in to follow this  

  • Recently Browsing   0 members

    No registered users viewing this page.

×
×
  • Create New...