Difference between revisions of "Documentation/DevGuide/AppendixB/File structure"

From Apache OpenOffice Wiki
Jump to: navigation, search
(FINAL VERSION FOR L10N)
Line 41: Line 41:
 
For legal reasons, the header has to be exactly as shown in the following snippet. Exceptions of this rule are the dynamic parts within "<code>$...$</code>" and the list of contributors at the end.
 
For legal reasons, the header has to be exactly as shown in the following snippet. Exceptions of this rule are the dynamic parts within "<code>$...$</code>" and the list of contributors at the end.
  
  /*************************************************************************
+
  <!--***********************************************************
  *
+
*  
  * OpenOffice.org - a multi-platform office productivity suite
+
  * Licensed to the Apache Software Foundation (ASF) under one
  *
+
* or more contributor license agreements. See the NOTICE file
  $RCSfile: MyNewIDLType.idl,v $
+
  * distributed with this work for additional information
  *
+
  * regarding copyright ownership. The ASF licenses this file
  * $Revision: 1.0 $
+
* to you under the Apache License, Version 2.0 (the
  *
+
* "License"); you may not use this file except in compliance
  * last change: $Author: jsc $ $Date: 2005/09/07 20:25:41 $
+
* with the License. You may obtain a copy of the License at
  *
+
*  
  *  The Contents of this file are made available subject to
+
*   http://www.apache.org/licenses/LICENSE-2.0
  * the terms of GNU Lesser General Public License Version 2.1.
+
*  
  *
+
* Unless required by applicable law or agreed to in writing,
  *
+
* software distributed under the License is distributed on an
  *    GNU Lesser General Public License Version 2.1
+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  *   =============================================
+
* KIND, either express or implied.  See the License for the
  *   Copyright 2007 by Sun Microsystems, Inc.
+
* specific language governing permissions and limitations
  *   901 San Antonio Road, Palo Alto, CA 94303, USA
+
* under the License.
  *  
+
  *  
  *   This library is free software; you can redistribute it and/or
+
***********************************************************-->
  *    modify it under the terms of the GNU Lesser General Public
+
  *    License version 2.1, as published by the Free Software Foundation.
+
  *
+
  *    This library is distributed in the hope that it will be useful,
+
  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
+
  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+
  *    Lesser General Public License for more details.
+
  *
+
  *   You should have received a copy of the GNU Lesser General Public
+
  *    License along with this library; if not, write to the Free Software
+
  *    Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+
  *    MA 02111-1307  USA 
+
  *
+
  ************************************************************************/
+
 
+
The filename in "<code>$RCSfile: MyNewIDLType.idl,v $</code>" is replaced automatically by the version control system, as well as "<code>$Revision: 1.1 $", "$Author: jsc $</code>" and "<code>$Date: 2007/07/05 10:30:56 $</code>". Contributors add their names to the list at the end.
+
 
+
The copyright date has to be adapted to the actual last year of work on the file.
+
  
 
The <code>#ifdef</code> and <code>#define</code> identifiers consist of two underscores "<code>__</code>", the module specification, each nested module separated by a single underscore "<code>_</code>" and the name of the file separated with a single underscore "<code>_</code>" as shown above and trailing two underscores "<code>__</code>".
 
The <code>#ifdef</code> and <code>#define</code> identifiers consist of two underscores "<code>__</code>", the module specification, each nested module separated by a single underscore "<code>_</code>" and the name of the file separated with a single underscore "<code>_</code>" as shown above and trailing two underscores "<code>__</code>".

Revision as of 14:03, 22 December 2020



This chapter provides information about the parts of each idl file, such as the header, body and footer, the character set to be used and the general layout to be applied.

General

Length of Lines

Lines in the idl files should not be longer than 78 characters, and documentation comment lines should not be longer than 75 characters. The preferable length of lines is upto 70 characters. This makes it readable in any ASCII editor and allows slight changes, that is, due to English proofreading without the need of reformatting.

Character Set and Special Characters

Only 7-bit ASCII characters are used in UNOIDL, even in the documentation comments. If other characters are necessary, the XHTML representation is to be used. See http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent for a list of the encodings.

Completeness of Sentences

In general, build grammatically complete sentences. One exception is the first sentence of an elements documentation, it may begin with a lowercase letter, in which case the described element itself is the implied subject.

Indentation

The indentation of sub-elements and for others is four spaces for each level of indentation.

Delimiters

Each major element has to be delimited by a 75 to 78-character long line from the other major elements. This line consists of “//” followed by equal signs to match the regular expression "^/\*=*$". Place it immediately in the line above the documentation comment that it belongs to.

Major elements are typedef, exception, struct, constants, enum, interface and service.

The sub elements can be delimited by a 75 to 78-character long line matched by the regular expression "^ \( \)*/\*-*$" from the other minor elements and the major element. This is a line consisting of a multiple of four spaces, followed by “//” and dashes. Place it immediately in the line above the documentation comment that it belongs to. Minor elements are structure and exception fields, methods and properties. Interfaces and services supported by services as single constants are to be grouped by delimiters.

Examples for major and minor elements are given below.

File-Header

For legal reasons, the header has to be exactly as shown in the following snippet. Exceptions of this rule are the dynamic parts within "$...$" and the list of contributors at the end.


The #ifdef and #define identifiers consist of two underscores "__", the module specification, each nested module separated by a single underscore "_" and the name of the file separated with a single underscore "_" as shown above and trailing two underscores "__".

File-Footer

The files do not have a footer with VCS fields. The history can only be viewed from CVS directly. This is to avoid endless expanding log lists.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages