Всем привет! Меня зовут Татьяна, я старший технический писатель в Orion Innovation. В нашей и без того большой команде мы используем достаточно обширный стек инструментов и технологий, но наиболее популярными и простыми в использовании являются XML-редакторы с поддержкой архитектуры DITA. Моя статья для технических писателей.
Особенно для тех из нас, кто, как и я, имеет гуманитарное образование.
Для разработчиков, особенно фронтенд-разработчиков, это может показаться элементарными вещами, но для технических писателей информация может оказаться полезной.
CSS в Oxygen, обзор для гуманитариев На сегодняшний день нашими основными инструментами для работы являются Oxygen XML Editor и Author. Подробно описывать их преимущества не буду — это заняло бы полстатьи.
Примерно то же самое можно сказать и о недостатках, кстати.
В этой статье я хочу выделить один аспект — использование стилей CSS для настройки готовых документов в различных форматах.
Более того, мы рассмотрим использование этих стилей теми, для кого программирование и языки программирования и разметки, даже если это html или css, — темный лес, несмотря на годы работы в IT. Те авторы, которые сегодня работают в основном с документацией для конечных пользователей, вероятно, разделят мою боль.
Наши клиенты часто предпочитают, чтобы документацию для конечных пользователей писали люди, максимально далекие от разработки и имеющие лишь условное представление об ИТ.
Считается, что таким образом можно избежать последствий профессиональной деформации разработчика, а инструкции будут представлены максимально четко, с четкой структурой и без ненужных информационных дампов и данных, которые не понадобятся пользователю.
Умение писателя ясно и понятно изложить и не ввести пользователя в заблуждение зачастую важнее для клиентов, чем опыт коммерческого кодирования и доскональное знание продукта изнутри, с той стороны, которая видна разработчикам, а не пользователям.
Поэтому большинство моих коллег имеют лингвистическое образование.
Конечно, у этой медали есть две стороны, вторая — мы, технические писатели с гуманитарным образованием, не всегда можем с одинаковой эффективностью использовать доступные разработчикам инструменты и технологии.
Я знаю технических специалистов, которые впадают в уныние при виде простого CSS-скрипта.
К счастью, при работе с Oxygen использование CSS для настройки результатов не кажется непосильной задачей.
Главным образом потому, что и Автор, и, в гораздо большей степени, Редактор предлагают достаточно разнообразный набор встроенных инструментов для работы с CSS и очень гибкую систему их использования.
Для их использования достаточно базовых знаний самого CSS.
Автор Oxygen против редактора Oxygen
Давайте сразу определим разницу.По сути, Editor включает в себя Author и дополнительный блок для разработчиков Oxygen Developer. Авторский инструмент — его будет достаточно, если вы просто хотите редактировать XML-файлы в визуальном редакторе и выводить их в разные выходные форматы.
Что касается использования CSS в Author, существует ряд ограничений.
Сюда входит ограниченная поддержка CSS-селекторов и достаточно жесткая иерархия приоритетов CSS-источников, о которых нужно всегда помнить, чтобы четко знать, где именно нужно изменить значения для определенного элемента, чтобы они отображались корректно.
.
Инструмент «Редактор» предоставляет вам гораздо больше возможностей для применения CSS и настройки.
Особенно, если вам посчастливилось иметь доступ к PDF Chemistry — инструменту, который преобразует XML или HTML в PDF с использованием CSS в режиме WYSIWYG. К сожалению, цены на него начинаются от месячной зарплаты программиста, поэтому рассматривать его мы не будем.
Но в Oxygen Editor также есть встроенный конвертер, и если вы работаете не в авторском режиме, вы можете использовать LESS в дополнение к стандартному CSS. Теперь давайте подробнее рассмотрим принципы работы с CSS для обоих режимов.
CSS в Oxygen Автор
Существует два основных способа добавления стилей в авторском режиме.Во-первых, даже если вы абсолютно ничего не делали, Oxygen автоматически применит стили по умолчанию к любому документу.
В принципе, если вам нужно создать какой-то документ быстро и без претензий на дизайнерскую красоту, с упором на содержание, их вам будет достаточно.
Но все же давайте поговорим о кастомизации.
Первый способ — применить CSS к конкретному документу.
Для этого выберите в меню Документ > XML-документ действие Ассоциированный XSLT/CSS Таблица стилей и в самом начале документа напишите следующее:
в данном случае мы используем CSS-атрибут @type, который сообщает нам правильный синтаксис для интерпретации таблицы стилей и ссылку на вашу пользовательскую таблицу стилей.<Эxml-stylesheet type="text/css" href="MyStyle.css"?>
Логичный вопрос — где взять или как написать эту кастомную таблицу, поскольку в начале статьи мы договорились, что рассматриваем способы работы с CSS для тех, кто им открыто владеет? К счастью для нас, в Интернете можно найти множество готовых вариантов.
Не нужно использовать их бездумно, поэтому так или иначе вам придется разбираться в основных CSS-атрибутах и селекторах и уметь хотя бы «читать» таблицы стилей.
Этот метод хорош для тех технических команд, в состав которых входят дизайнеры, способные предоставить готовые таблицы.
Все, что вам нужно сделать, это соединить их.
Второй способ — управлять таблицами стилей не для конкретного документа, а для конкретного типа документа.
Это делается в меню настроек Параметры → Настройки → Связь с типом документа.
На подвкладке CSS для режима «Автор» вы можете увидеть все стили, связанные с этим типом документа.
Если вы работаете в проекте с разными уровнями доступа, убедитесь, что у вас настроены права редактирования для этого раздела.
Таблицы стилей, перечисленные на этой вкладке, могут быть первичными или вторичными.
Стили, добавленные на эту вложенную вкладку, будут отображаться в том же порядке в раскрывающемся меню.
Стили .
На вкладке вы можете удалять, редактировать, добавлять таблицы, присваивать им свойства первичных или вторичных, объединять вторичные стили для их одновременного использования.
Кроме того, особенно если вы оффлайн-писатель и настраиваете доступ к функциям Oxygen самостоятельно, а не у своего системного администратора, у вас чаще всего будет доступ к возможности редактировать стили через CSS Inspector. 
Он открывается из контекстного меню, по умолчанию — справа.
На вкладке «Элемент» в тексте отобразятся правила для выбранного вами элемента.
Нажав на правило, вы откроете актуальный код CSS. И теперь вы можете это изменить.
Думаю, даже для тех писателей, которые не очень хорошо разбираются в CSS, очевидно, что это не сложная задача, большинство названий атрибутов говорят сами за себя.
Например, на этом рисунке есть CSS для элемента заголовка.
Собственно, на этом возможности добавления CSS в Авторском режиме практически исчерпываются.
Давайте рассмотрим принципы работы со стилями в Редакторе.
CSS в редакторе Oxygen
Здесь у нас гораздо более широкое поле для действий.В Редакторе можно применять не только CSS, но и LESS, причем не только на уровне документов или типов документов, но и на уровне отдельных страниц, тем или даже отдельных элементов и классов.
Что важно знать? Все методы добавления CSS в редактор имеют свой приоритет. Важно учитывать, где вы пишете определенные настройки, чтобы убедиться, что они не пересекаются со стилями, написанными где-то еще.
Что еще важно знать? Если вы свободно владеете CSS и таблицы стилей шаблонов вам не предоставляют дизайнеры, разрабатывающие фирменный стиль, то лучше положиться на дефолтные, благо в Oxygen их довольно много и есть из чего выбрать.
от, особенно если долизывание дизайна до современного состояния не является приоритетом.
Опять же, если разбить задачи на мелкие, в Интернете можно найти массу примеров кода для них.
В то же время освойтесь с CSS. Давайте рассмотрим настройки CSS в порядке приоритета, от самых общих до конкретных, где настройки в конце списка будут перекрывать предыдущие.
- Сначала загружаются настройки из таблицы по умолчанию, кислород.css. Они применяются ко всем проектам и добавляются по умолчанию, если они не перекрываются более узкими таблицами стилей.
- Страница.
css
или Шаблон.css
.Затем они выгружаются и переопределяют настройки по умолчанию.
Это стили, связанные с шаблонами или страницами.
Если вы добавите какие-либо стили через ID меню конкретного элемента, то эти стили будут добавлены сюда строго в том порядке, в котором они были добавлены, то есть самые новые будут загружены последними.
- Универсальный.
css.
Глобальная таблица стилей, в которой мы настоятельно рекомендуем никогда ничего не изменять вручную.На этом этапе добавляются стили по умолчанию для различных компонентов Oxygen, стили из таблиц, управляемых самим Oxygen, и стили из пользовательских селекторов Oxygen. Именно в таком порядке!
- CSS внутри страниц.
- CSS, который вы добавляете с помощью тега Кодовый блок .
Добавление CSS к элементу
Чтобы добавить настройки к конкретному элементу, выберите в его настройках Дополнительно → Пользовательский CSS .Обратите внимание: если вы совсем не доверяете своим навыкам работы с CSS, вкладка «Дополнительно» позволяет редактировать некоторые настройки в визуальном режиме, как и в режиме «Автор».
Например, макет, шрифты и т. д. И еще важный момент: во вкладке Custom CSS закрывающая скобка уже добавлена в самом низу, поэтому отдельно ее добавлять не нужно.
Информация об этом стиле будет храниться в папке \wp-content\uploads\oxygen\css и использоваться ТОЛЬКО на этой странице.
Добавление CSS с использованием блока кода
Самый удобный и быстрый способ настройки, используемый локально.Если внутри Кодовый блок Есть только CSS, расположение тега на странице не важно.
Опять же, эти настройки будут использоваться только на конкретной странице.
Использование таблиц стилей
Удобно, если вам нужно применить настройки ко всем страницам сайта.Вы можете добавить таблицы стилей через меню.
Управление > Таблицы стилей .
В этом случае они будут выгружены из Universal.css и применены везде в документе.
Если в каком-то конкретном случае вы хотите использовать другой стиль для определенного контента, используйте Code Block. Это переопределит настройки из таблиц.
Есть еще такой огромный и очень важный пласт работы с CSS, как тонкая настройка CSS при работе со сценариями трансформации, то есть когда вы преобразуете исходный материал в конкретный вывод. Например, PDF-файл или онлайн-справка.
Но мы не будем это описывать; оно заслуживает отдельной статьи или даже небольшой монографии.
Итак, мы рассмотрели, где в Oxygen можно настроить внешний вид ваших документов, обозначили разные способы это сделать и разобрались, как и где редактировать настройки, чтобы нужные вам CSS-правила не переписывались где-то еще и контент отображается корректно.
Надеюсь, этот небольшой обзор был полезен, и, возможно, у вас есть свои лайфхаки, как использовать CSS, не слишком углубляясь в тонкости, поделитесь ими в комментариях.
Теги: #CSS #Подготовка технической документации #документация #xml #dita #технический писатель #Oxygen #редактор xml
-
Как Часто Вы Смотрите Сериалы/Мультсериалы?
19 Oct, 24 -
О Правильных Инструментах
19 Oct, 24 -
Чудеса Тригонометрии С Использованием Холста
19 Oct, 24
