[docs] Re: ALT packaging docs

Kirill Maslinsky kirill на altlinux.ru
Вт Ноя 16 15:09:24 MSK 2004


Добрый день!

> >>Нужна возможность в (сделанном в каждой странице) подвале оставлять 
> >>комментарии и поправки, которые будут фиксироваться в bugzilla;
> >>   
> >Наверное, это стоит делать не ниже уровня chapter/article?
> > 
> Нет, у нас section в любой момент могут стать chapter.

Должна быть возможность оставлять комментарии и поправки на _каждой_ странице
html, вне зависимости от того, раздел какого уровня представлен на этой
странице. Потому что если пользователь заметит ошибку на странице, 
где такого подвала не оказалось -- ему придётся как-то искать, к какому 
разделу относится эта страница...

> >Еще хорошо бы добиться соответствия идентификатора главы и имени
> >компонента в Bugzilla.

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

> Если уж углубляться сейчас в технические детали, я бы предложил 
> компоненты задавать вручную, либо по корневому id публикуемой части 
> документации (например, id книги, если публикуется какое из 
> "Руководств"), либо придумать из головы. А имена пакетов брать из id 
> того структурного элемента, на который строчится кляуза.

Вообще есть и другой способ сообщить об ошибках в документации: 
вся документация упакована в rpm-пакеты, а на них штатным образом 
можно повесить ошибку, как и на любой пакет в Сизифе.
Нужно ли как-то разводить или совмещать этот способ с вешанием ошибок 
именно на содержание документации?

> У меня уже есть стиль, который создаёт id всем структурным элементам 
> (set|book|part|partintro и так далее), которые id не имеют.
> 
> При именовании html по id во время сборки, проблем со связью документа и 
> кляузы на него не должно быть.

Хорошее решение. Что-нибудь мешает использовать этот стиль при генерации 
html-dir в наших Makeile'ах? Это всяко лучше, чем туманное "ch1s1", 
а я стараюсь следить за тем, чтобы у каждого раздела был осмысленный id.

-- 
Kirill Maslinsky
ALT Linux Team * Documentation Project   



Подробная информация о списке рассылки docs