1  #!/usr/bin/python3
  2  #
  3  # Copyright (c) 2016-2019 The Khronos Group Inc.
  4  #
  5  # Licensed under the Apache License, Version 2.0 (the "License");
  6  # you may not use this file except in compliance with the License.
  7  # You may obtain a copy of the License at
  8  #
  9  #     http://www.apache.org/licenses/LICENSE-2.0
 10  #
 11  # Unless required by applicable law or agreed to in writing, software
 12  # distributed under the License is distributed on an "AS IS" BASIS,
 13  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 14  # See the License for the specific language governing permissions and
 15  # limitations under the License.
 16  
 17  # insertTags.py - insert // refBegin and // refEnd tags in Vulkan
 18  # spec source files.
 19  #
 20  # Usage: insertTags.py output-dir files
 21  
 22  # Short descriptions of ref pages, if not found
 23  from refDesc import *
 24  
 25  # Utility functions
 26  from reflib import *
 27  import copy, os, pdb, re, string, sys
 28  
 29  # Insert informative tags in a spec asciidoc source file
 30  #   specFile - filename to add tags to
 31  #   baseDir - output directory to generate page in
 32  def insertTags(specFile, baseDir):
 33      file = loadFile(specFile)
 34      if (file == None):
 35          return
 36      pageMap = findRefs(file)
 37      logDiag(specFile + ': found', len(pageMap.keys()), 'potential pages')
 38  
 39      # Fix up references in pageMap
 40      fixupRefs(pageMap, specFile, file)
 41  
 42      # Proceed backwards through the file, inserting
 43      # // refBegin name desc
 44      # lines where they're meaningful
 45  
 46      logDiag('Table of pages found:')
 47      logDiag('---------------------')
 48      for name in pageMap.keys():
 49          printPageInfo(pageMap[name], file)
 50  
 51      line = len(file) - 1
 52      while (line >= 0):
 53          # If this is a valid begin line without a description, and a
 54          # description exists in refDesc, add it.
 55          for name in pageMap.keys():
 56              pi = pageMap[name]
 57              if (pi.begin == line):
 58                  if (not name in refDesc.keys()):
 59                      if (pi.desc != None):
 60                          logDiag('Description already exists, but no refDesc found for', name, 'at', specFile + ':' + str(line))
 61                      else:
 62                          if (pi.embed):
 63                              logDiag('No refDesc found (this is OK) for embedded', name, 'at', specFile + ':' + str(line))
 64                          else:
 65                              logWarn('No refDesc found for', name, 'at', specFile + ':' + str(line))
 66                      continue
 67  
 68                  # New or replacement refBegin line, with short description
 69                  newLine = '// refBegin ' + name + ' - ' + refDesc[name] + '\n'
 70  
 71                  if (pi.desc == None):
 72                      logDiag('Adding description for', name, 'at', specFile + ':' + str(line))
 73  
 74                      # If there's already a refBegin on this line, replace it.
 75                      # Otherwise, insert one.
 76                      if (file[line].find('// refBegin') == 0):
 77                          logDiag('Replacing existing refBegin without description for', name, 'at', specFile + ':' + str(line))
 78                          file[line] = newLine
 79                      else:
 80                          logDiag('Inserting new refBegin at', specFile + ':' + str(line))
 81                          # Add a blank line after the comment if it's new
 82                          file.insert(line, newLine)
 83                          file.insert(line, '\n')
 84                  else:
 85                      if (pi.desc[-1] == '.'):
 86                          pi.desc = pi.desc[0:-1]
 87                      if (pi.desc == refDesc[name]):
 88                          logDiag('Not replacing description for', name, 'at', specFile + ':' + str(line), '- MATCHES existing one')
 89                      else:
 90                          logWarn('Replacing existing refBegin WITH description for', name, 'at', specFile + ':' + str(line))
 91                          file[line] = newLine
 92                          # logWarn('\t  refDesc: ', refDesc[name])
 93                          # logWarn('\tfile desc: ', pi.desc)
 94  
 95          line = line - 1
 96  
 97      pageName = baseDir + '/' + os.path.basename(specFile)
 98      logDiag('Creating output file', pageName)
 99      fp = open(pageName, 'w', encoding='utf-8')
100      fp.writelines(file)
101      fp.close()
102  
103  
104  if __name__ == '__main__':
105      logDiag('In main!')
106  
107      baseDir = 'man'
108      follow = False
109      if (len(sys.argv) > 2):
110          baseDir = sys.argv[1]
111          for file in sys.argv[2:]:
112              insertTags(file, baseDir)