Sık Kullanılan XML Ögeleri

Sık Kullanılan XML Ögeleri

S1000D farkındalık yaratma blog serimiz kapsamında daha önce XML temel kavramlarına (bk. S1000D için Temel XML Bilgisi) ve S1000D şemalarına (bk. S1000D Şemaları) değinmiştik. Bu blog yazımızda ise S1000D şemaları tarafından yaygın olarak kullanılan XML ögelerini (elements) ve özniteliklerini teknik detaya girmeden kullanım amaçlarını ve kullanırken dikkat edilmesi gereken hususları ön planda tutarak anlatacağız.

Esasında S1000D dışında herhangi bir doküman hazırlarken sık sık ihtiyacımız olan bu yapılara hepimiz aşinayız. Herhangi bir word dokümanı hazırlarken paragraf, liste, tablo, şekil vb. temel yapıların en az birini veya hepsini beraber kullanmaktayız.

Benzer şekilde bu yapıların XML ögesi bakış açısıyla doğru olarak kullanılması kaliteli S1000D uyumlu teknik dokümanlar üretmemize önemli katkılar sunmaktadır. Bu çerçevede, S1000D şemaları tarafından yaygın olarak kullanılan temel XML öğeleri aşağıda açıklanmıştır.

1. Metinsel ögeler

1.1 Paragraf <para>

Metinsel bilgileri sunmak için en çok kullanılan öge <para> ögesidir. Bu öge kullanılarak veri modüllerine metin doğrudan, başka bir alt öğe seçmeden eklenebilir. Ancak, bir paragraf sadece metinsel içerikten oluşmayabilir. Bir paragrafı istenen şekilde oluşturmak için <para> ögesi çeşitli alt ögelerin kullanımını mümkün hale getirmektedir. Bir paragraf oluştururken sıklıkla ihtiyaç duyulan alt ögelerin bazıları aşağıda listelenmiştir:

  • Sıralı liste (sequential list),
  • Sırasız liste (random list),
  • Sembol (symbol) (bk. Sembol),
  • Kısaltma (Acronym),
  • Vurgu (emphasis (Bold, italic,..))
  • Referans (bk. Referanslar)

Bir paragraf yukarıdaki ögelerin hiçbiri kullanılmadan (sadece düz metin varsa) veya hepsi (bk. Şekil 1- Paragraf <para>) kullanılarak oluşturulabilir.

<para> ögesinin tüm alt ögelerini öğrenmek için S1000D spesifikasyonuna bakabilirsiniz.  

Şekil 1 – Paragraf <para>

1.2 Düzeyli paragraf <levelledPara>

Teknik dokümanlarda içerik oluştururken kullanılan diğer bir öge ise <levelledPara> veya düzeyli paragraftır.

Düzeyli paragraf ögesi kullanılarak içerikler bölümlere ayrılabilir, bu bölümler çok seviyeli, hiyerarşik bir şekilde sunulabilir.

Düzeyli paragraf ögesi farklı alt ögeler içerebilir:

  • Başlık (<title>)
  • Paragraf(<para>)
  • Düzeyli paragraf (<leveledPara>)
  • Tablo (<table>)
  • Figür (<figure>)

Düzeyli paragraf ögesi sınırsız sayıda aynı düzeyde veya iç içe alt düzeyli paragraf öğesi içerebilir. Fakat, S1000D 5 seviyeden fazlası iç içe düzeyli paragraf kullanımını önermemektedir. Bunun yanı sıra, her seviyede en az 2 adet alt düzeyli paragraf ögesinin eklenmesini tavsiye etmektedir.

Şekil 2 – Düzeyli paragraf <levelledPara>

2. Görseller

2.1 Görsel <figure>

En çok kullanılan ögelerden biri de görsel ögesidir. S1000D görsel kullanımını yazılan metni daha anlaşılır bir hale getirmesi için kullanılmasını önerir. Her görsel aktarmak istediği bilgiyi net, en basit ve yalın şekli ile içermeli ve okuyucuda herhangi bir kafa karışıklığına neden olmamalıdır. Görsel gereksiz ve kullanışsız ilave bilgi barındırmamalıdır. 

Eklenen görsellerin ilgili metnin hemen sonrasına veya en yakın yere eklenmesini önermektedir.  Eğer S1000D uyumlu teknik dokümanın PDF çıktısında görsel ve ilgili metin aynı sayfada değilse S1000D görseli manuel yöntemler ile taşınmasına izin vermemektedir.

Görsel ögesinin aşağıdaki alt ögeleri kullanılarak teknik dokümanlara görsel eklenebilir:

  • Görsel adı (<title>)
  • Bir veya daha fazla görsel <graphic> 

Not: Görsel başlığı cümle biçiminde (Sentence case) yazılmalı ve sonunda nokta [.] içermemelidir. Görsel başlığının uzunluğu maksimum iki satır olmalıdır.

Şekil 3 – Görsel <figure>

2.2 Etkin nokta <hotspot>

Bir görselde farklı bölgeleri etkin nokta olarak tanımlanıp, metin ile ilişkilendirebilir. Bu özelik sayesinde kullanıcıya daha açıklayıcı ve anlaşılır bir bilgi sunulur.  Görselde mevcut olan her etkin noktanın bilgileri <hotspot> ögesi kullanılarak tanımlanır. Böylece:

  • Görseldeki etkin noktalar arasında
  • Etkin nokta ve metin arasında
  • Etkin nokta ve başka bir veri modülü arasında

Referanslar (bk. Referanslar) kurularak bilgiler görsel olarak daha anlaşılır ve açıklayıcı bir şekilde sunulabilir.  

Şekil 4 – Etkin nokta <hotspot>

2.3 Sembol <symbol>

Teknik dokümanlarda satır içerisine görsel eklemek bu öge sayesinde mümkündür. Semboller, emniyet tedbirleri (bk. Emniyet tedbirleri ve notlar) (UYARI, DİKKAT ve NOT) eklenirken de kullanılabilir.

Şekil 5 – Satır içi sembol

Şekil 6 – Emniyet tedbiri sembol

3. Tablo <table>

Veri modüllerinde bilgileri tablo formatında sunmak için <table> ögesi kullanılır. Tablo oluşturulurken aşağıdaki üç öge yaygın olarak kullanılmaktadır.:

  • Tablo adı (table title)
  • Tablo başlık satırı (table header)
  • Tablo gövdesi (table body)

Not: Tablo adı cümle biçiminde (Sentence case) yazılmalı ve sonunda nokta [.] içermemelidir. Tablo başlığının uzunluğu maksimum iki satır olmalıdır.

Şekil 7 – Tablo <table>

4. Referanslar

Sunulan bilgi hakkında kullanıcıya daha fazla bilgi veya ilişkili bir konuya yönlendirmek için referanslar kullanılır. S1000D iki farklı referans türü tanımlamaktadır:

  • İç referans
  • Dış referans

4.1 İç referans

İç referans aynı veri modül içerisinde başka bir ögeye (paragraf, görsel, tablo, etkin nokta, vb.) referans vermek için kullanılır.

4.2 Dış referans

Dış referans ise başka bir veri modülü, harici dokümanlara referans vermek için kullanılır.  Referans verilen harici dokümanlar S1000D uyumlu olmayan eski veri (legacy data) olabilir.

5. Emniyet tedbirleri ve notlar

Teknik dokümanlara emniyet tedbiri ve not eklemek için aşağıdaki ögeler kullanılmaktadır:

  • Uyarı (<warning>)
  • Dikkat (<caution>)
  • Not (<note> )

Uyarı olarak tanımlanan emniyet tedbiri doğru şekilde uygulanmadığında personelin yaralanmasına ya da hayatını kaybetmesine neden olabilecek prosedürler, İşlem adımları, uygulamalar vb. bilgileri içerir.

Dikkat olarak tanımlanan emniyet tedbiri takip edilmemesi durumunda ekipmanın zarar görmesine ya da kullanılamaz hale gelmesine neden olabilecek prosedürler, işlem adımları, uygulamalar vb. bilgileri içerir.

Not kullanılarak kullanıcıya vurgulanmak istenen açıklama vb. bilgiler sunulur.

Not: S1000D, sadece tanım/tanıtım içeren veri modülleri (örneğin bilgi kodu 040 olan veri modüller) uyarı/dikkat kullanımını önermemektedir.

Şekil 8 – Emniyet tedbirleri ve not

Hazırlayan: Sanem DAĞHAN